@wix/agent-skills 1.6.0 → 1.7.0

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

@@ -1,225 +1,25 @@
-# CMS Foundations — Shared Patterns for `@wix/data`
+# CMS Foundations — Seeding via `@wix/data` REST (business track)
 
-Core patterns used by all CMS use cases: service module template, `@wix/data` queries, image resolution, elevated access, MCP seeding, and rich-text (Ricos) rendering.
+The **seeding** half of CMS foundations: create collections and insert + verify sample items via the Wix Data REST API. This is frontend-blind business-track work — a collection and its items are the same regardless of what renders them.
 
-> **Import note (read first).** Page code in this plugin uses `import * as items from "@wix/wix-data-items-sdk"` rather than the documented `import { items } from "@wix/data"`. The Wix-headless docs still show the `@wix/data` form, 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 (with `query`, `insert`, `update`, `remove`, `bulkInsert`, etc.) lives in `@wix/wix-data-items-sdk`, which `@wix/data` depends on transitively. Importing from there directly works on every current `@wix/data` version. The cms vertical pack adds `@wix/wix-data-items-sdk` to the install list so it's always present (`references/verticals/cms.md`). Use the wix-data-items-sdk import everywhere.
+> **Rendering / page code lives in the astro frontend track.** The service-module template, `@wix/data` SDK query patterns, image resolution, Ricos rendering, and category filtering are **not** here — they are in `<SKILL_ROOT>/references/astro/cms/CMS_FOUNDATIONS.md` (the `pages` scope's doc). This file is consumed by the `seed` scope. The `cms/INSTRUCTIONS.md` router points each scope at the right half.
 
-## Rendering Ricos rich-text fields
+## Collection ID Format (seeding-relevant)
 
-Wix CMS stores `RICH_TEXT` / `RICH_CONTENT` fields as **Ricos JSON** — a structured node tree (PARAGRAPH, HEADING, BULLETED_LIST, etc.), not HTML. The dashboard's rich-text editor reads and writes this format.
+Native (user-created) CMS collections use **just the collection name** — no namespace prefix (e.g. `"about-content"`, `"faq"`, `"Projects"`). Only Wix App collections use a `<namespace>/<name>` format. Use the exact `id` you create here; verify with `GET /wix-data/v2/collections?fields=id` (standard REST headers from `../shared/AUTHENTICATION.md`). Never guess — the dashboard display name may differ from the ID.
 
-For SSR Astro pages (about, faq, portfolio, team, resource), import the seeded `renderRicos` util from `src/utils/ricos.ts`. The util is shipped by `seed-utilities.sh` (copied from `<SKILL_ROOT>/shared-utilities/ricos.ts` during Setup), so it's already on disk — do NOT inline a Ricos walker in your page.
+## Seeding via REST (Conditional)
 
-```astro
----
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-import { renderRicos } from "../utils/ricos";
-
-const elevatedQuery = auth.elevate(items.query);
-const { items: results } = await elevatedQuery("about-content")
-  .limit(1)
-  .find();
-const about = results[0];
-const bodyHtml = renderRicos(about?.body);
----
-
-<article class="prose">
-  <h1>{about?.heading}</h1>
-  <div set:html={bodyHtml} />
-</article>
-```
-
-The util covers the common subset (PARAGRAPH, HEADING 1-6, BULLETED_LIST / ORDERED_LIST / LIST_ITEM, BLOCKQUOTE, DIVIDER + BOLD / ITALIC / UNDERLINE / LINK decorations). Anything outside that set renders defensively as a `<p>` with the raw text — never throws.
-
-> **Why not @wix/ricos?** The blog vertical uses `@wix/ricos`'s React `RicosViewer` as a client island because blog posts can carry the full Ricos feature set (galleries, polls, embedded media). For static CMS pages, that's ~80kb of React for paragraphs and lists — overkill. Use the seeded SSR walker instead.
-
-> **Do NOT `set:html={item.body}` directly.** That ships JSON-encoded text into the page (e.g. `[object Object]` or `{"nodes":...}`). Always go through `renderRicos`.
-
-> **Critical Rules — Read Before Starting**
-> 1. **Collection IDs have NO namespace** — user collections use just the name (e.g., `"Projects"`). Only Wix App collections use `<namespace>/<name>`. Verify via MCP: `GET /wix-data/v2/collections?fields=id`.
-> 2. **SDK query pattern** — `items.query("CollectionId").find()`. There is no `items.queryDataItems()` in the SDK.
-> 3. **`auth.elevate` on every query** — without it, restricted collections silently return no items.
-> 4. **CMS only for user collections** — use `@wix/blog` for blog posts, `@wix/stores` for products, `@wix/forms` for form submissions.
-
-## Prerequisites
-
-- `@wix/data` package installed (collected by features orchestrator — do NOT install independently)
-- `@wix/essentials` package installed (for elevation)
-- A data collection created in the Wix dashboard → CMS section
-- No special Wix app installation needed — `@wix/data` works with any Wix Managed Headless project
-
-## Collection ID Format
-
-Native (user-created) CMS collections use **just the collection name** — no namespace prefix.
-
-Example: if the collection is called `Projects`, the collection ID is simply `"Projects"`.
-
-Only Wix App collections (e.g., `Members/PublicData`, `Locations/Locations`) use a `<namespace>/<name>` format. User-created collections never use a namespace.
-
-> **How to verify**: Call `GET /wix-data/v2/collections?fields=id` via MCP and use the exact `id` value from the response. Never guess — the dashboard name may differ from the ID.
-
-## Quick Reference — Inline Query (Simple Pages)
-
-For pages that just need to list items from a collection:
-
-```astro
----
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-
-// Always elevate queries for permission safety
-const elevatedQuery = auth.elevate(items.query);
-const { items: results } = await elevatedQuery("MyCollection")
-  .ascending("sortField")
-  .limit(50)
-  .find();
-
-// Fields are directly on each item (NOT item.data.field)
-const myItems = results.map((item) => ({
-  name: item.name,        // correct
-  // name: item.data.name  // wrong — REST pattern, not SDK
-}));
----
-```
-
-> **Common mistake:** `items.queryDataItems(...)` does NOT exist in the
-> `@wix/data` SDK. The REST API uses `/items/query` with a `dataCollectionId`
-> body field, but the SDK uses `items.query("collectionId")` — a chainable
-> QueryBuilder. Do not confuse REST and SDK patterns.
-
-## Service Module Template
-
-Every CMS use case follows the same `src/lib/{usecase}.ts` pattern — a typed interface and query functions that pages import.
-
-```typescript
-import * as items from "@wix/wix-data-items-sdk";
-import { auth } from "@wix/essentials";
-import { media } from "@wix/sdk";
-
-// -- Collection ID (use exact name from Wix dashboard — no namespace for native collections) --
-const COLLECTION_ID = "collection-name";
-
-// -- Typed interface matching collection fields --
-export interface CollectionItem {
-  _id: string;
-  title: string;
-  slug: string;
-  // ...add fields matching your collection schema
-  coverImage?: string;
-}
-
-// -- Image resolution helper --
-function resolveImage(wixImageUrl: string | undefined, width = 800, height = 600): string | undefined {
-  if (!wixImageUrl) return undefined;
-  return media.getScaledToFillImageUrl(wixImageUrl, width, height, {});
-}
-
-// -- Query all items --
-// Wrap every Wix SDK await in try/catch. If the query throws at SSR, an empty
-// array keeps the page renderable instead of crashing it. (Unguarded SSR
-// awaits truncate Astro's response stream mid-body — nav renders, then blank.)
-export async function queryItems(): Promise<CollectionItem[]> {
-  try {
-    const elevatedQuery = auth.elevate(items.query);
-    const { items: results } = await elevatedQuery(COLLECTION_ID)
-      .ascending("orderIndex")
-      .limit(50)
-      .find();
-
-    return results.map((item) => ({
-      ...item,
-      coverImage: resolveImage(item.coverImage),
-    })) as CollectionItem[];
-  } catch (err) {
-    console.error(`[cms:${COLLECTION_ID}] query failed:`, err);
-    return [];
-  }
-}
-
-// -- Get single item by slug --
-export async function getItemBySlug(slug: string): Promise<CollectionItem | null> {
-  try {
-    const elevatedQuery = auth.elevate(items.query);
-    const { items: results } = await elevatedQuery(COLLECTION_ID)
-      .eq("slug", slug)
-      .limit(1)
-      .find();
-
-    const item = results[0];
-    if (!item) return null;
-
-    return {
-      ...item,
-      coverImage: resolveImage(item.coverImage),
-    } as CollectionItem;
-  } catch (err) {
-    console.error(`[cms:${COLLECTION_ID}] getItemBySlug failed:`, err);
-    return null;
-  }
-}
-```
-
-Key details:
-- `auth.elevate(items.query)` wraps the query for restricted collections — always use this by default since collection permissions vary
-- `media.getScaledToFillImageUrl(url, w, h, {})` resolves `wix:image://` URLs to sized CDN URLs
-- Sort by `orderIndex` (ascending) for manually ordered content, or `_createdDate` (descending) for chronological
-- The interface must match the collection fields — check the dashboard, don't guess
-
-## Multi-Image Resolution
-
-For collections with image arrays (e.g., gallery images):
-
-```typescript
-function resolveImages(imageUrls: string[] | undefined, width = 800, height = 600): string[] {
-  if (!imageUrls || imageUrls.length === 0) return [];
-  return imageUrls
-    .map((url) => media.getScaledToFillImageUrl(url, width, height, {}))
-    .filter(Boolean);
-}
-```
-
-## Category Filtering Pattern
-
-Many use cases filter by category via URL search params (server-rendered, no client JS):
-
-```astro
----
-const activeCategory = Astro.url.searchParams.get("category");
-const allItems = await queryItems();
-const filtered = activeCategory
-  ? allItems.filter((item) => item.category === activeCategory)
-  : allItems;
-const categories = [...new Set(allItems.map((item) => item.category).filter(Boolean))];
----
-
-<nav>
-  <a href="?" class:list={[!activeCategory && "active"]}>All</a>
-  {categories.map((cat) => (
-    <a
-      href={`?category=${encodeURIComponent(cat)}`}
-      class:list={[activeCategory === cat && "active"]}
-    >{cat}</a>
-  ))}
-</nav>
-```
-
-> **Styling note:** Category filter pill styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Category Filter.
-
-## MCP Seeding (Conditional)
-
-If Wix MCP tools are available, check if the collection has data and seed sample items if empty. This is **conditional** — only attempt if MCP is connected.
+Check whether the collection already has data; seed sample items only if empty. Calls go through `curl` against `wixapis.com` with the site-scoped REST token (see `../shared/AUTHENTICATION.md`) — no SDK, no MCP.
 
 1. Query the collection — if items exist, skip seeding
-2. If empty, create the collection and insert sample items via MCP (see templates below)
+2. If empty, create the collection and insert sample items via the REST calls below
 3. Design sample data that matches the business type from the functional plan
 
-> MCP seeding is optional. If MCP tools are not available, instruct the user to add content via the Wix dashboard → CMS section.
-
 ### Create collection (if it doesn't exist)
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/collections
+REST: POST https://www.wixapis.com/wix-data/v2/collections
 body: {
   "collection": {
     "id": "about-content",
@@ -238,7 +38,7 @@ body: {
 **This is the critical step that must include actual field values.** Creating an item without populating the `data` object results in an empty record — the collection schema exists but the item has no content.
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items
+REST: POST https://www.wixapis.com/wix-data/v2/items
 body: {
   "dataCollectionId": "about-content",
   "dataItem": {
@@ -257,7 +57,7 @@ The response returns the created item's `_id` — collect these for the Phase 1
 For FAQ items, include both `question` and `answer` plus `sortOrder`:
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items
+REST: POST https://www.wixapis.com/wix-data/v2/items
 body: {
   "dataCollectionId": "faq",
   "dataItem": {
@@ -275,7 +75,7 @@ body: {
 After inserting all items, **query each collection once** and confirm every field you sent is present in the stored `data`. A POST without errors does NOT prove the content persisted — the API has accepted insert bodies with missing fields before, and the failure is invisible until a human opens the page.
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items/query
+REST: POST https://www.wixapis.com/wix-data/v2/items/query
 body: { "dataCollectionId": "<collection>" }
 ```
 
@@ -287,12 +87,13 @@ For every returned item, confirm its `data` object contains every text field you
 
 A CMS seeder can return `complete` for an about-content item, then Image Phase 2 silently wipes its `heading` + `body` via a destructive full-record PUT. The verify-after-insert step here plus the read-merge-PUT rule in the images agent makes that class of data loss unreachable.
 
-### MCP Seeding with Images
+### Seeding with Images
 
 For use cases with image fields (`photo`, `coverImage`, `galleryImages`),
-follow `../../shared/IMAGE_GENERATION.md` (Steps 1–2) for Wix AI image
-generation and Wix Media import. Image generation is MCP-authenticated
-and always available — do not ask the user for credentials.
+follow `../shared/IMAGE_GENERATION.md` (Steps 1–2) for Wix AI image
+generation and Wix Media import. Image generation goes through the same
+CLI-minted REST token as the rest of this skill — do not ask the user for
+credentials.
 
 **Workflow:**
 
@@ -303,14 +104,14 @@ and always available — do not ask the user for credentials.
 
 ```
 # Step a: read the existing item
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/wix-data/v2/items/query
+REST: POST https://www.wixapis.com/wix-data/v2/items/query
 body: {
   "dataCollectionId": "CollectionName",
   "query": { "filter": { "_id": { "$in": ["{itemId}"] } } }
 }
 
 # Step b: merge image into existing data and PUT the full record
-<prefix>CallWixSiteAPI: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}
+REST: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}
 body: {
   "dataCollectionId": "CollectionName",
   "dataItem": {
@@ -322,18 +123,18 @@ body: {
 
 `...existingData` must include every non-system field from step a (system fields `_id`, `_owner`, `_createdDate`, `_updatedDate` don't need to be echoed). Skipping the merge wipes seeded text fields and ships an empty About page.
 
-**Prompt templates** — each use-case reference defines its own prompt template (see the "Seed with Images" section in TEAM_DIRECTORY.md, PORTFOLIO.md, RESOURCE_LIBRARY.md). Always incorporate brand context from the discovery/design phases.
+**Prompt templates** — each use-case reference defines its own prompt template (see the "Seed with Images" section in `../astro/cms/TEAM_DIRECTORY.md`, `../astro/cms/PORTFOLIO.md`, `../astro/cms/RESOURCE_LIBRARY.md`). Always incorporate brand context from the discovery/design phases.
 
 **Constraints:**
 - Never block the main flow on image failures — text data is already seeded
 - Runware image URLs are short-lived — import to Wix Media immediately after generation
 - If image generation or import fails for a single item, skip that item and continue with others
-- If all generation fails (credits exhausted, MCP errors), write the sidecar with `Status: partial` and proceed — but always attempt first
-- FAQ_KNOWLEDGE_BASE has no image fields — skip image generation for FAQ use cases
+- If all generation fails (credits exhausted, upstream Runware errors), write the sidecar with `Status: partial` and proceed — but always attempt first
+- `../astro/cms/FAQ_KNOWLEDGE_BASE.md` has no image fields — skip image generation for FAQ use cases
 
 ## Return Results
 
-Emit a structured JSON block at the end of your completion message per `../../shared/RETURN_CONTRACT.md`. Do NOT write sidecar files.
+Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do NOT write sidecar files.
 
 ```json
 {
@@ -359,15 +160,15 @@ Emit a structured JSON block at the end of your completion message per `../../sh
 ```
 
 - `storedFields` MUST match the real keys seen in the verify-after-insert query response's `data` object (see § "Verify inserts with a live query"). Downstream pages agents compare against this — if you return `fields: ["heading", "body"]` but only `heading` was actually stored, pages render empty bodies.
-- `sampleValues` is a single example item's field-to-short-string map. Lets downstream agents spot-check that content is real without another MCP round-trip. Truncate rich-text bodies to the first ~80 characters.
+- `sampleValues` is a single example item's field-to-short-string map. Lets downstream agents spot-check that content is real without another REST round-trip. Truncate rich-text bodies to the first ~80 characters.
 - For collections without image fields (e.g., FAQ), set `imageField: null`.
 - The JSON block MUST be the last content in your message.
 
-## Testing
+## Testing (seed-side)
+
+1. Create a data collection in the Wix dashboard → CMS (or via the REST `POST /collections` above).
+2. Add fields matching the use case schema (see the specific use case reference under `../astro/cms/`).
+3. Add at least 2–3 items with all fields populated, including `slug` and `published` (if applicable).
+4. Run the verify-after-insert query and confirm every field persisted.
 
-1. Create a data collection in the Wix dashboard → CMS
-2. Add fields matching the use case schema (see the specific use case reference)
-3. Add at least 2–3 items with all fields populated, including `slug` and `published` (if applicable)
-4. Run `npx @wix/cli dev`
-5. Navigate to the listing page — should show items
-6. Click an item — should navigate to the detail page
+Page rendering / SDK query patterns for these collections are in `../astro/cms/CMS_FOUNDATIONS.md`.

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

@@ -5,14 +5,14 @@ description: "Implements structured content pages (About, FAQ, portfolios, team
 
 # CMS 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 (no site.json reads), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (create collections + seed items via MCP) | `./CMS_FOUNDATIONS.md` (§ seeding) + use-case ref |
-| `pages` | Pages (About + FAQ pages read CMS via @wix/data inline) | `./CMS_FOUNDATIONS.md` (§ code patterns) + use-case ref |
+| `seed` | Seed (create collections + seed items via REST) | `./CMS_FOUNDATIONS.md` (seeding, business half) + use-case ref under `../astro/cms/` (collection schema + seed-with-images) |
+| `pages` | Pages (About + FAQ pages read CMS via @wix/data inline) | `../astro/cms/CMS_FOUNDATIONS.md` (code patterns) + use-case ref under `../astro/cms/` |
 
 No `components` scope — CMS pages SSR content inline via `@wix/data`; no React islands.
 
@@ -20,21 +20,26 @@ No `components` scope — CMS pages SSR content inline via `@wix/data`; no React
 
 Pick based on the business type (the orchestrator names one in your prompt):
 
-- `./FAQ_KNOWLEDGE_BASE.md` — Q&A accordions, category sections, search
-- `./PORTFOLIO.md` — project grid, category filter tabs, project detail
-- `./TEAM_DIRECTORY.md` — department-grouped directory, staff cards
-- `./RESOURCE_LIBRARY.md` — file listings, download buttons, file type badges
+- `../astro/cms/FAQ_KNOWLEDGE_BASE.md` — Q&A accordions, category sections, search
+- `../astro/cms/PORTFOLIO.md` — project grid, category filter tabs, project detail
+- `../astro/cms/TEAM_DIRECTORY.md` — department-grouped directory, staff cards
+- `../astro/cms/RESOURCE_LIBRARY.md` — file listings, download buttons, file type badges
 
 ## Files this vertical creates / contributes
 
 See `<SKILL_ROOT>/references/verticals/cms.md` frontmatter.
 
+## Page width (FAQ, About, long-form CMS)
+
+Read `references/shared/STYLING.md` § "Prose / reading width". **Do not** wrap FAQ/About body copy in `max-w-3xl` unless `--container-3xl` exists in `src/styles/global.css` `@theme`. Prefer `container-reading`, `max-w-6xl` (when `--container-6xl` is defined), or `max-w-[48rem]`. A bare `max-w-3xl` with only a spacing scale ships a ~80px column.
+
 ## CMS-specific failure modes
 
 | Wrong | Right |
 |---|---|
 | `items.queryDataItems(...)` / `items.query({ dataCollectionId })` | `items.query("CollectionId").find()` — queryDataItems doesn't exist |
 | React islands for static content pages | SSR inline with `@wix/data`; no islands needed |
+| `max-w-3xl` on FAQ/About wrappers without `--container-3xl` in `@theme` | `container-reading` or `max-w-[48rem]` / `max-w-6xl` per STYLING.md |
 | Return `status: "complete"` without re-querying the collection | Always run the verify-after-insert query (see CMS_FOUNDATIONS.md § "Verify inserts with a live query"); fail fast if any field is missing |
 | Report `fields: [...]` guessed from the insert body | Report `storedFields: [...]` matching the actual keys in the query response's `data` object — pages agents compare against these |
-| Assume text fields survive downstream image PATCHes | Seeder's job is to verify content is present; images agent must preserve via read-merge-PUT (images INSTRUCTIONS.md § "CMS Items") |
+| Assume text fields survive downstream image PATCHes | Seeder's job is to verify content is present; images agent must preserve via read-merge-PUT (images INSTRUCTIONS.md § "CMS Items") |

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

@@ -0,0 +1,38 @@
+---
+name: custom-frontend
+description: "Routing target for the custom (non-astro) frontend track. Custom is any frontend the user brings that is not astro. The frontend-authoring track is NOT available yet — astro is the only supported frontend. This stub surfaces the not-available message and records the intended future shape; it does not attempt to author a site."
+---
+
+# Custom (non-astro) frontend — not available yet
+
+**Astro is the only supported frontend today.** This doc is the routing target for every non-astro `frontend` value. When the conductor routes here, it does **not** attempt frontend authoring — it surfaces the message below and stops the frontend track.
+
+## What to tell the user
+
+> Custom (non-astro) frontends are not available yet — **astro is the supported frontend**. Re-run with the astro frontend, or check back later.
+
+Do **not** scaffold, design, compose, or wire anything. Do **not** fall back to a half-built site. There is no per-pack custom authoring to dispatch — that work is deferred (see "Intended future shape" below).
+
+## Why this is a stub
+
+The frontend track is the only track that branches on the `frontend` axis (`PLAN.md` § "Two tracks"). It routes to exactly one of:
+
+| `frontend` | Frontend-track instructions | Status |
+|---|---|---|
+| `astro` | `<SKILL_ROOT>/references/astro/` (full playbook) | **Supported** |
+| custom (anything else) | this file | **Not available yet** |
+
+Astro is the one Wix-preferred frontend the skill builds end-to-end. Every other frontend is the user's own choice; standing up the authoring track for those is deferred until the custom track is prioritized.
+
+## Intended future shape (documented, not built)
+
+When the custom track is prioritized, it will follow the premise below. **None of this runs today** — it is recorded here as the target so the eventual build has a spec.
+
+1. **Scaffold** — `npm create @wix/new@latest init` wraps the user's *existing* project (vs `headless` for astro), writes `wix.config.json`, and sets `site.outputDirectory` to the directory containing the entry file. (`wix release` is framework-tolerant via `wix.config.json.site.outputDirectory`.)
+2. **Business track (shared, frontend-blind)** — Setup (app installs from a project analysis, `env pull` if needed) and Seed run the **same** frontend-blind path as astro. Per the two-track model, a product/collection/post/form is the same regardless of what renders it, so this track does not change for custom.
+3. **Frontend authoring (the deferred new work)** — per-pack wiring guides under `references/custom/<pack>/…` that inject `@wix/sdk` calls into the user's existing files, **additive-only**, via a heuristic inject-point ladder: explicit `data-wix-*` attribute → semantic class → return a recommendation rather than guessing. This is what the custom track delivers when it is built.
+4. **Release** — `npx @wix/cli@latest release` directly, **no build** (the user's project is published as-is, or the user runs their own build first).
+
+### Historical reference
+
+The retired "Integrate" (Path B) flow — `SETUP.md` § "Existing project flow" E1–E6, especially the **E4 SDK-wiring recipe** — is the closest prior art for step 3 above. It is kept as a **historical reference only**, not a Beta deliverable. Do not dispatch it; the conductor no longer routes non-astro frontends into it.

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

@@ -5,17 +5,17 @@ description: "Implements vertical-agnostic ecommerce — cart page, checkout red
 
 # Ecom 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 (no site.json reads), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `components` | Components (CartView, CartBadge — TSX only, **no CSS**) — `src/utils/discounts.ts` is pre-copied by the orchestrator | `./CART_WIRING.md` |
-| `components-css` | Components (scoped CSS — `components-ecom.css` only; runs concurrently with `components`) | `./COMPONENTS_CSS.md` |
-| `pages` | Pages (cart.astro, thank-you.astro, Navigation CartBadge mount) | `./CART_PAGES.md` |
+| `components` | Components (CartView, CartBadge — TSX only, **no CSS**) — `src/utils/discounts.ts` is pre-copied by the orchestrator | `../astro/ecom/CART_WIRING.md` |
+| ~~`components-css`~~ | **Do not dispatch.** `src/styles/components-ecom.css` is copied from `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css` by the orchestrator's pre-Step-4.5 batch (see BUILD.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` | Pages (cart.astro, thank-you.astro, Navigation CartBadge mount) | `../astro/ecom/CART_PAGES.md` |
 
-> **Why `components` is split.** A single agent writing the .tsx islands plus the scoped CSS was Phase 3's critical path on the most recent run (204 s for ecom alone). 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. Mirrors the stores split. See `./COMPONENTS_CSS.md` § "What this scope owns".
+> **Why `components` is split.** A single agent writing the .tsx islands plus the scoped CSS was Phase 3's critical path on the most recent run (204 s for ecom alone). 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. Mirrors the stores split. See `../astro/ecom/COMPONENTS_CSS.md` § "What this scope owns".
 
 Note: `ecom` is never triggered independently — it's co-loaded by verticals that require it (`stores` today; `bookings`, `events` in the future). No `seed` scope — ecom has no data of its own; it works off line items from whichever catalog app is installed.
 
@@ -26,15 +26,15 @@ See `<SKILL_ROOT>/references/verticals/ecom.md` frontmatter.
 ## Templates
 
 Components (`components` scope — TSX only):
-- `<SKILL_ROOT>/templates/ecom/CartView.tsx`
-- `<SKILL_ROOT>/templates/ecom/CartBadge.tsx`
+- `<SKILL_ROOT>/references/astro/templates/ecom/CartView.tsx`
+- `<SKILL_ROOT>/references/astro/templates/ecom/CartBadge.tsx`
 
 Components CSS (`components-css` scope — scoped CSS only):
-- `<SKILL_ROOT>/templates/ecom/components-ecom.css`
+- `<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css`
 
 ### Pre-copied by the orchestrator (do NOT write this yourself)
 
-- `src/utils/discounts.ts` — pre-copied from `<SKILL_ROOT>/templates/ecom/discounts.ts` BEFORE your `components` scope dispatches. Wix Ecom Discount Rules fetch + per-product match utility; consumers are stores `pages-products` / `pages-home-and-nav` (ProductCard ribbon + product-detail offer callout). Uses `auth.elevate()` from `@wix/essentials` — `discountRules.queryDiscountRules` requires `ECOM.DISCOUNT_RULES_READ`, a visitor client returns empty silently without elevation.
+- `src/utils/discounts.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/ecom/discounts.ts` BEFORE your `components` scope dispatches. Wix Ecom Discount Rules fetch + per-product match utility; consumers are stores `pages-products` / `pages-home-and-nav` (ProductCard ribbon + product-detail offer callout). Uses `auth.elevate()` from `@wix/essentials` — `discountRules.queryDiscountRules` requires `ECOM.DISCOUNT_RULES_READ`, a visitor client returns empty silently without elevation.
 
   Just import from this path; never rewrite the file. Regenerating it has shipped a no-op stub that satisfied the manifest but caused the discount ribbon to silently never render. The pre-copy makes that regression structurally impossible.
 
@@ -56,4 +56,4 @@ See `references/shared/STYLING.md` § "Component-specific CSS is owned by the co
 
 `cart-updated` CustomEvent on `window`:
 - **Dispatchers:** `AddToCartButton` (stores), `CartView` (ecom)
-- **Listener:** `CartBadge` (ecom)
+- **Listener:** `CartBadge` (ecom)

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

@@ -5,15 +5,15 @@ description: "Implements contact, lead, and signup forms via @wix/forms. Scopes:
 
 # Forms 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 (no site.json reads), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (Forms app install + form creation + postSubmissionTriggers PATCH) | `./CONTACT_FORM.md` (§ Form Setup) |
-| `components` | Components (ContactForm.tsx React island) | `./CONTACT_FORM.md` (§ React island) |
-| `pages` | Pages (contact.astro wire with formId from seeded data) | `./CONTACT_FORM.md` (§ Page wiring) |
+| `seed` | Seed (Forms app install + form creation + postSubmissionTriggers PATCH) | `../astro/forms/CONTACT_FORM.md` (§ Form Setup) |
+| `components` | Components (ContactForm.tsx React island) | `../astro/forms/CONTACT_FORM.md` (§ React island) |
+| `pages` | Pages (contact.astro wire with formId from seeded data) | `../astro/forms/CONTACT_FORM.md` (§ Page wiring) |
 
 ## Files this vertical creates / contributes
 
@@ -40,4 +40,4 @@ The `seed` scope adapts field selection based on business purpose from the funct
 | Skip `auth.elevate` when listing forms | `listForms` requires elevated permissions |
 | Submit forms from server-side code | Form submission must be client-side (React island with `client:load`) |
 | Detect textarea by `componentType === "TEXT_AREA"` | Check `identifier === "TEXT_AREA"` or `target === "message"` |
-| Hardcode form field IDs or form ID | Use `forms.listForms("wix.form_app.form")` with `auth.elevate` for runtime discovery |
+| Hardcode form field IDs or form ID | Use `forms.listForms("wix.form_app.form")` with `auth.elevate` for runtime discovery |

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

@@ -5,14 +5,14 @@ description: "Implements the passive Wix Gift Cards vertical — runtime probe u
 
 # Gift Cards 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 (no site.json reads), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `components` | Components (probe util, React island, scoped CSS) | `./COMPONENTS.md` |
-| `pages` | Pages (gift-cards landing + Navigation/index patches) | `./PAGES.md` |
+| `components` | Components (probe util, React island, scoped CSS) | `../astro/gift-cards/COMPONENTS.md` |
+| `pages` | Pages (gift-cards landing + Navigation/index patches) | `../astro/gift-cards/PAGES.md` |
 
 This pack has **no `seed` scope** — the dashboard's eGift Card template is the source of truth and we never seed denominations from code.
 
@@ -26,17 +26,17 @@ Before returning `status: "complete"` from the `pages` scope, verify every file
 
 ## Templates
 
-Canonical templates live at `<SKILL_ROOT>/templates/gift-cards/`. 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/gift-cards/`. Your `components` and `pages` scopes read these and adapt them — don't invent markup or logic.
 
 Components (`components` scope):
-- `<SKILL_ROOT>/templates/gift-cards/gift-cards.ts`
-- `<SKILL_ROOT>/templates/gift-cards/GiftCardPurchase.tsx`
-- `<SKILL_ROOT>/templates/gift-cards/components-gift-cards.css`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/gift-cards.ts`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/GiftCardPurchase.tsx`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/components-gift-cards.css`
 
 Pages (`pages` scope):
-- `<SKILL_ROOT>/templates/gift-cards/gift-cards.astro`
-- `<SKILL_ROOT>/templates/gift-cards/_nav-snippet.astro` — exact contribution to insert at `<!-- nav:links -->` in `Navigation.astro`
-- `<SKILL_ROOT>/templates/gift-cards/_home-teaser-snippet.astro` — exact contribution to insert at `<!-- home:gift-cards -->` in `index.astro`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/gift-cards.astro`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/_nav-snippet.astro` — exact contribution to insert at `<!-- nav:links -->` in `Navigation.astro`
+- `<SKILL_ROOT>/references/astro/templates/gift-cards/_home-teaser-snippet.astro` — exact contribution to insert at `<!-- home:gift-cards -->` in `index.astro`
 
 ## Gift-cards-specific failure modes
 
@@ -48,4 +48,4 @@ Pages (`pages` scope):
 | Forget to import `getGiftCardProduct` when patching `Navigation.astro` or `index.astro` | When inserting at a marker, also add the corresponding import + frontmatter call to that file |
 | Drop or rename the marker comment after inserting | Preserve the marker line — future re-runs and other verticals depend on it |
 | Render the page when probe returns `null` | Redirect to `/` (`Astro.redirect("/", 302)`) so users following stale links never see a broken page |
-| Skip memoization of `getGiftCardProduct()` | Module-level cache promise — Navigation, home, and page render in the same request and must coalesce to one fetch |
+| Skip memoization of `getGiftCardProduct()` | Module-level cache promise — Navigation, home, and page render in the same request and must coalesce to one fetch |