@wix/agent-skills 1.6.0 → 1.8.0

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 (read only your `.wix/seeded.json` slice), 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-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` | 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 TSX-only.** The scoped CSS (`src/styles/components-ecom.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 the `components-css` scope-routing row above) rather than being written by an agent. 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,21 +26,21 @@ 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`
+Components CSS (pre-copied by the orchestrator — no agent writes it):
+- `<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.
 
 ## CSS ownership — ecom pack
 
-Ecom-specific component CSS lives in `src/styles/components-ecom.css` (written by your `components` scope), NOT in the designer's `global.css`. The classes you own:
+Ecom-specific component CSS lives in `src/styles/components-ecom.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components-css` scope-routing row above; your `components` scope imports it, never writes it), NOT in the designer's `global.css`. The classes the pack owns:
 
 - `.cart-summary` — the bordered/sticky summary panel on `/cart`. Compound bordered card; sticky on desktop.
 - `.cart-total` — the row inside the summary that anchors the total amount with a top rule and display-serif typography.
@@ -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,19 +5,19 @@ 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 (read only your `.wix/seeded.json` slice), 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
 
-See `<SKILL_ROOT>/references/verticals/forms.md` frontmatter.
+Each scope's files are enumerated in `../astro/forms/CONTACT_FORM.md` (§ Form Setup, § React island, § Page wiring).
 
 ## Form purpose variants
 
@@ -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,38 +5,38 @@ 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 (read only your `.wix/seeded.json` slice), 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.
 
 ## Files this vertical creates / contributes
 
-See `<SKILL_ROOT>/references/verticals/gift-cards.md` frontmatter (`creates:` and `contributes:` blocks).
+See the § "Templates" list below for the files each scope produces (and the nav/home contributions it patches).
 
 ## Pre-return file-existence assertion (pages scope)
 
-Before returning `status: "complete"` from the `pages` scope, verify every file in `creates:` (phase: pages) plus the patched files in `contributes:` exists on disk. If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
+Before returning `status: "complete"` from the `pages` scope, verify every file the scope produces (the page templates in § "Templates" below, plus the patched `Navigation.astro` / `index.astro`) exists on disk. If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
 
 ## 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 |

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

@@ -1,11 +1,11 @@
 ---
 name: images-agent
-description: "Generates images for the site. Two scopes: image-phase-1-decorative (hero/about/background art, no dependencies, dispatched in Step 3) and image-phase-2-entity (product/blog/CMS item images, needs Phase 1 Seed entity IDs, dispatched in Step 4.5 alongside Phase 3 Components)."
+description: "Generates images for the site. Two scopes: image-phase-1-decorative (hero/about/background art) and image-phase-2-entity (product/blog/CMS item images, needs Phase 1 Seed entity IDs)."
 ---
 
 # Images Agent — Scope-Based Image Generation
 
-Generates site images in two scopes dispatched separately by the parent skill. Uses Wix AI (Runware) for generation and Wix Media for hosting — all via MCP, no user credentials required.
+Generates site images in two scopes. Uses Wix AI (Runware) for generation and Wix Media for hosting — all via `curl` against `wixapis.com` using the CLI-minted REST token (see `../shared/AUTHENTICATION.md`).
 
 **Nothing else blocks on image generation.** Phases 1–4 and the core pipeline all proceed independently. Products, posts, and pages work without images. Each image phase enriches them when it finishes.
 
@@ -13,21 +13,21 @@ Generates site images in two scopes dispatched separately by the parent skill. U
 
 Your prompt includes `Scope: <name>`. Map it to an image phase:
 
-| Scope | When dispatched | Depends on | Output |
-|---|---|---|---|
-| `image-phase-1-decorative` | Step 3 (background) | Brand context only | Decorative images for hero / about / backgrounds; written to `.wix/image-urls.md` |
-| `image-phase-2-entity` | Step 4.5 (background, alongside Phase 3 Components) | Phase 1 Seed return data (entity IDs in prompt) | Entity images attached to products / blog posts / CMS items via MCP PATCH |
+| Scope | Depends on | Output |
+|---|---|---|
+| `image-phase-1-decorative` | Brand context only | Decorative images for hero / about / backgrounds; slot→URL map returned in `data.slots` |
+| `image-phase-2-entity` | Phase 1 Seed return data (entity IDs in prompt) | Entity images attached to products / blog posts / CMS items via REST PATCH |
 
 If your prompt is missing a `Scope:` line, stop and ask the parent — do not guess.
 
 ## Self-Loading
 
 1. Read `../shared/IMAGE_GENERATION.md` — Wix AI image generation + Wix Media import recipe (including the **required** batched-call pattern)
-2. Read `../shared/MCP_PREFIX.md` — MCP tool prefix for Wix API calls
+2. Read `../shared/DOCS_SEARCH.md` — REST auth for Wix API calls
 3. **Prefer the inlined recipe below and `IMAGE_GENERATION.md` over external docs.** When a PATCH or API call fails:
    1. **FIRST re-read your own recipe** in this file (INSTRUCTIONS.md § for that entity type) — it likely covers the error.
    2. If the recipe covers it, follow the recipe. Do NOT look up external docs for errors your recipe already handles.
-   3. **ONLY** if you've re-read the recipe AND the error is genuinely not covered, fall back to `SearchWixRESTDocumentation` / `ReadFullDocsArticle`.
+   3. **ONLY** if you've re-read the recipe AND the error is genuinely not covered, fall back to `docs-search REST (see DOCS_SEARCH.md)` / `raw-docs REST (see DOCS_SEARCH.md)`.
    
    Known errors already covered by this recipe (do not look up externally):
    - **428** from product PATCH → missing `options`/`variantsInfo` → see § "Products" step 1
@@ -36,19 +36,23 @@ If your prompt is missing a `Scope:` line, stop and ask the parent — do not gu
    - **400** `unsupportedDimensions` → see § "Error Handling"
    - **400** `invalidTaskUUID` → `taskUUID` must be valid UUIDv4 → see § "Quick Reference"
 
-## Quick Reference: Generation Call Shape
+## Preferred: generate + import via `generate-images.mjs`
 
-Before the first MCP call, ensure the `CallWixSiteAPI` tool schema is loaded (the orchestrator's Step 0 MCP bootstrap covers this for the whole session per `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` — only re-load if you hit a tool-not-found error). Use your runtime's tool-discovery primitive to look up the suffix.
+**Run the phase's generation + Wix Media import through `<SKILL_ROOT>/scripts/generate-images.mjs`** (see `../shared/IMAGE_GENERATION.md` § "Preferred: run the whole phase through `generate-images.mjs`"). Build the image list — one entry per slot (Phase 1) or per entity (Phase 2), each with `{key, positivePrompt, width, height}` — and pipe it in with the run's cached `WIX_TOKEN`. The script fires all generations concurrently in-process and returns a `key → {url, fileId}` map plus a `slots` (key→url) convenience map. This is the deterministic form of the "one concurrent batch" rule — it cannot serialize and cannot hit the `google:4@2` N≥3 504. Then attach: Phase 1 → `write-decorative-json.mjs`; Phase 2 → the per-entity PATCH/PUT/publish recipe in this file. **You still own prompt construction** (brand-contextual, per the guidelines) and **entity attachment**; the script owns the parallel network round-trips only.
 
-**All generation tool calls for an image phase MUST be in one concurrent batch.** The exact shape depends on the model — see `../shared/IMAGE_GENERATION.md` § "Required: minimize round-trips" for the rule. In short:
+## Quick Reference: Generation Call Shape (manual fallback)
 
-- **`google:4@2` (the default):** N concurrent 1-task `CallWixSiteAPI` calls as siblings in one batch. (Batched N≥3 times out at 504 on this model.)
-- **`bfl:5@1`, `runware:400@1`:** one batched `CallWixSiteAPI` call with N tasks in the body array.
+The shapes below are the **reference bodies** the script builds, and the **fallback** if you hand-drive generation. Before the first REST call, ensure the `curl` tool schema is loaded (the orchestrator's session auth covers this for the whole session per `<SKILL_ROOT>/references/shared/AUTHENTICATION.md` — only re-load if you hit a tool-not-found error). Use your runtime's AUTHENTICATION.md recovery ladder to look up the suffix.
+
+**If you do hand-drive it, all generation tool calls for an image phase MUST be in one concurrent batch.** The exact shape depends on the model — see `../shared/IMAGE_GENERATION.md` § "Required (manual fallback): minimize round-trips" for the rule. In short:
+
+- **`google:4@2` (the default):** N concurrent 1-task `curl` calls as siblings in one batch. (Batched N≥3 times out at 504 on this model.)
+- **`bfl:5@1`, `runware:400@1`:** one batched `curl` call with N tasks in the body array.
 
 Example task body (same for both patterns — only the distribution across tool calls changes):
 
 ```
-<prefix>CallWixSiteAPI: POST https://www.wixapis.com/runwareschemaless/v1/request
+REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 body: [
   {
     "taskType": "imageInference",
@@ -93,11 +97,11 @@ Concurrent siblings are safe across all three stages (gen, import, PATCH). Wix M
 
 Image Phase 2 for N products + M CMS items: ~1 schema-load + 1 product query + 1 batched generate + (N+M) imports + (N+M) PATCHes ≈ 2(N+M) + 3 calls. For 4 entities that's ~11 calls. If above 20, check for unnecessary doc reads or re-queries.
 
-## Scope: `image-phase-1-decorative` (Step 3 — no dependencies)
+## Scope: `image-phase-1-decorative` (no dependencies)
 
 Generate site-wide decorative images that don't depend on any entity. Used by the Phase 2 Design System agent + Phase 4 Pages agents for hero sections, about pages, and backgrounds.
 
-**What to generate** is determined by the `decorativeSlots` list in your prompt — generate exactly those keys, no more, no less. Typical canonical keys: `hero`, `about`, `productsHeader`, `cmsHeader`. Do not invent additional keys (`background`, `aboutFeature`, etc.) — orphan keys ship as unused images and unfilled slots show as empty placeholders. The orchestrator composes this list from the loaded verticals + the designer's slot vocabulary (`references/designer/INSTRUCTIONS.md` § common rule #7); the two must agree.
+**What to generate** is determined by the `decorativeSlots` list in your prompt — generate exactly those keys, no more, no less. Typical canonical keys: `hero`, `about`, `productsHeader`, `cmsHeader`. Do not invent additional keys (`background`, `aboutFeature`, etc.) — orphan keys ship as unused images and unfilled slots show as empty placeholders. The orchestrator composes this list from the loaded verticals + the designer's slot vocabulary (`references/astro/designer/INSTRUCTIONS.md` § common rule #7); the two must agree.
 
 **Inputs (from your prompt):**
 - Brand name, business type, aesthetic direction
@@ -108,25 +112,16 @@ Generate site-wide decorative images that don't depend on any entity. Used by th
 **Process (must follow this order):**
 
 1. **Craft all image prompts up front** using brand context — see `IMAGE_GENERATION.md` § "Prompt guidelines".
-2. **Dispatch all generation tool calls in one concurrent batch** — siblings for `google:4@2` (1 task each, N blocks in parallel), or one batched call for other models (N tasks in `body`). Required, not optional — see `IMAGE_GENERATION.md` § "Required: minimize round-trips per image phase". Sequential 1-task calls across multiple turns is an anti-pattern; never do it.
-3. **Import each to Wix Media** via `<prefix>CallWixSiteAPI: POST /site-media/v1/files/import`. Imports can parallelize (sibling `CallWixSiteAPI` tool calls in one message).
-4. **Write `.wix/image-urls.md`** with all resolved URLs, keyed by purpose:
-   ```markdown
-   # Image URLs
-
-   ## hero
-   - url: https://static.wixstatic.com/media/...
+2. **Generate + import via `generate-images.mjs`** (preferred — § "Preferred: generate + import" above): build the `images` list (`key` = slot name, e.g. `hero`/`about`) and run the script with the cached `WIX_TOKEN`; it fires all generations concurrently and returns the `slots` map. **Manual fallback only:** follow § "Mandatory pre-call procedure" above (construct ALL tasks first, dispatch in one concurrent batch).
+3. **Import each to Wix Media** via `REST: POST https://www.wixapis.com/site-media/v1/files/import`.
+4. **Collect the resolved URLs keyed by slot purpose** (e.g., `{"hero": "https://static.wixstatic.com/...", "about": "https://static.wixstatic.com/..."}`). This map goes into your return JSON under `data.slots` — see § Return below. Do NOT write `.wix/image-urls.md` or any other file; the orchestrator pipes your `data.slots` directly into `patch-decorative-slots.mjs` via stdin.
+5. Return the structured JSON block per `../shared/RETURN_CONTRACT.md` (see § Return below). The JSON return is your sole output channel.
 
-   ## about
-   - url: https://static.wixstatic.com/media/...
-   ```
-5. Return the structured JSON block per `../shared/RETURN_CONTRACT.md` (see § Return below).
-
-Page design agents read `.wix/image-urls.md` and use the URLs. If the file doesn't exist when a page agent runs, the page agent uses placeholder styling instead — nothing blocks.
+The orchestrator consumes your `data.slots` map via one of two deterministic scripts, depending on the frontend — **your output contract is identical either way** (a slot→URL map; you never touch frontend source): on **astro** it pipes the map into `patch-decorative-slots.mjs`, which injects `<img>` tags into the designer's `data-decorative-slot="<key>"` placeholders in `.astro` pages; on a **framework-SPA (`own`)** it pipes the map into `write-decorative-json.mjs`, which writes `src/decorative-images.json` for the generated app to import. Either way, if your return is missing or has no slots, the consumer is a no-op and the placeholders fall back to the designer's solid-color (themed-block) rendering — nothing blocks.
 
-## Scope: `image-phase-2-entity` (Step 4.5 — Phase 1 Seed data inline)
+## Scope: `image-phase-2-entity` (Phase 1 Seed data inline)
 
-Generate images for products, blog posts, and CMS items. Attach via MCP PATCH calls.
+Generate images for products, blog posts, and CMS items. Attach via REST PATCH calls (`curl` against `wixapis.com`).
 
 > **Parent must NOT paste a PATCH/Update body template.** This INSTRUCTIONS.md owns the recipe per entity type (Products, Blog Posts, CMS Items) — including the exact write-shape (`media.itemsInfo.items[].url` + echoed `options`/`variantsInfo` + `revision`, no `fieldMask`) and the failure-mode mappings. An inline template in the parent prompt causes drift; the wrong shape (e.g. `media.main.image` + `fieldMask`) returns `400 "Expected an object"` on every product. Parents should pass `Phase 1 Seed return data` and `Brand context` only.
 
@@ -135,21 +130,18 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 - `collections: [{name, itemIds, fields}, ...]` — if cms pack loaded
 - `blogPosts: [{id, title, ...}, ...]` — if blog pack loaded
 
-**Do not poll for sidecars.** `.wix/logs/<feature>-data.md` is a deprecated coordination pattern (see `../shared/RETURN_CONTRACT.md`). If the `Phase 1 Seed return data:` block is missing from your prompt, return `status: "failed"` with `reason: "Phase 1 Seed return data not provided; image-phase-2-entity cannot run without entity IDs"` — do not sleep, do not read sidecars, do not query Phase 1 Seed data from MCP.
+**Do not poll for sidecars.** Do not read `.wix/logs/<feature>-data.md` or any coordination file (see `../shared/RETURN_CONTRACT.md`). If the `Phase 1 Seed return data:` block is missing from your prompt, return `status: "failed"` with `reason: "Phase 1 Seed return data not provided; image-phase-2-entity cannot run without entity IDs"` — do not sleep, do not read sidecars, do not re-query Phase 1 Seed data.
 
 **Process per entity type (must follow):**
 
 1. **Craft all image prompts** for this entity type up front, using each entity's own context (name, description, title, etc.).
-2. **Dispatch all generation tool calls in one concurrent batch** — same dispatch shape as Phase 1 Decorative:
-   - For `google:4@2` (default): N parallel sibling `CallWixSiteAPI` tool calls, one task each.
-   - For `bfl:5@1` / `runware:400@1` / others: ONE batched call with all N tasks in `body`.
-   See `IMAGE_GENERATION.md` § "Required: minimize round-trips per image phase". Sequential 1-task calls across multiple turns is an anti-pattern.
+2. **Generate + import via `generate-images.mjs`** (preferred — § "Preferred: generate + import" above): build the `images` list with `key` = each entity's ID, run the script with the cached `WIX_TOKEN`, and read the returned `map[entityId].url` / `.fileId` for the attach step. The script generates all entity images concurrently and isolates per-image failures (`status: "partial"`) — including the `google:4@2` 504 retry below, handled in-script. **Manual fallback only:** follow § "Mandatory pre-call procedure" above (construct ALL tasks first, dispatch in one concurrent batch).
 
-   **`google:4@2` 504 retry.** Even with N concurrent siblings, individual tasks intermittently 504. When the response array contains an entry with `errorMessage: "Request timed out"` or HTTP 504, retry **only the failing task(s)** in a follow-up batch — do NOT re-dispatch the whole batch. Cap at 1 retry per task; if it 504s twice, fall back to `bfl:5@1` for that task or skip it (entity gets no image; user can upload from dashboard).
+   **`google:4@2` 504 retry** (manual fallback; the script does this for you). Even with N concurrent siblings, individual tasks intermittently 504. When the response array contains an entry with `errorMessage: "Request timed out"` or HTTP 504, retry **only the failing task(s)** in a follow-up batch — do NOT re-dispatch the whole batch. Cap at 1 retry per task; if it 504s twice, fall back to `bfl:5@1` for that task or skip it (entity gets no image; user can upload from dashboard).
 
-   **N≥6 entities — stagger.** When you have 6 or more entities of one type, split into pairs of 3 parallel siblings rather than 6+ in one shot. Runware throttles google:4@2 above ~4 concurrent tasks per request burst, and the timeout ladder gets steeper. Two messages with 3 siblings each is reliably faster than one message with 6 + multiple retries. (Heuristic — refine after more runs collect data.)
+   **N≥6 entities — stagger.** When you have 6 or more entities of one type, split into pairs of 3 parallel siblings rather than 6+ in one shot. Runware throttles google:4@2 above ~4 concurrent tasks per request burst, and the timeout ladder gets steeper. Two messages with 3 siblings each is reliably faster than one message with 6 + multiple retries.
 3. **Import each to Wix Media**. Imports can parallelize.
-4. **PATCH each entity** with its image URL / file ID. PATCH calls can also parallelize (sibling `CallWixSiteAPI` tool calls in one message).
+4. **PATCH each entity** with its image URL / file ID. PATCH calls can also parallelize (sibling `curl` tool calls in one message).
 
 ### Products (if `products` is in your prompt)
 
@@ -161,9 +153,9 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
    > **Use per-product GET instead of bulk query:**
    > ```
-   > <prefix>CallWixSiteAPI: GET /stores/v3/products/{productId}   // no body
+   > REST: GET https://www.wixapis.com/stores/v3/products/{productId}
    > ```
-   > GET returns both `options` and `variantsInfo` in one shot. Parallelize the N GETs as sibling `CallWixSiteAPI` tool calls in one concurrent batch so they fan out without adding to the critical path.
+   > GET returns both `options` and `variantsInfo` in one shot. Parallelize the N GETs as sibling `curl` tool calls in one concurrent batch so they fan out without adding to the critical path.
 
    > If you skip this and get a 428, re-read this section — do not look up external docs.
 
@@ -173,7 +165,7 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
 4. PATCH each product with its image + preserved options/variantsInfo + product `revision`:
    ```
-   <prefix>CallWixSiteAPI: PATCH /stores/v3/products/{productId}
+   REST: PATCH https://www.wixapis.com/stores/v3/products/{productId}
    body: {
      "product": {
        "revision": "<product.revision from step 1's GET>",
@@ -197,11 +189,11 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
    **409 `INVALID_REVISION` recovery.** If a single PATCH returns 409 with `{"applicationError": {"code": "INVALID_REVISION", ...}}`, the product's actual revision has advanced past the value you cached in step 1's GET. This typically happens against an already-built site (re-runs, remediation runs) where the user edited products via the dashboard between builds. Recovery is per-failure, not whole-batch:
 
-   1. Re-fetch the failed product: `<prefix>CallWixSiteAPI: GET /stores/v3/products/{productId}`. Read the new `revision`.
+   1. Re-fetch the failed product: `REST: GET https://www.wixapis.com/stores/v3/products/{productId}`.
    2. Retry the PATCH once with the new revision.
    3. If the retry also fails with 409, surface the error — something else is mutating the entity faster than we can react. Don't loop.
 
-   Successful PATCHes from the original parallel batch keep their state; only the 409'd entity needs the recovery. Cap at one retry per failed entity. Append to `run.json.recoveries[]`: `{ "code": "INVALID_REVISION_RETRY", "entityId": "<id>", "originalRevision": "<x>", "actualRevision": "<y>" }`.
+   Successful PATCHes from the original parallel batch keep their state; only the 409'd entity needs the recovery. Cap at one retry per failed entity.
 
 ### Blog Posts (if `blogPosts` is in your prompt)
 
@@ -213,7 +205,7 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
 4. PATCH each draft post's cover image:
    ```
-   <prefix>CallWixSiteAPI: PATCH /blog/v3/draft-posts/{draftPostId}
+   REST: PATCH https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}
    body: {
      "draftPost": {
        "media": { "wixMedia": { "image": { "id": "<file-id-from-fileUrl>" } } }
@@ -223,7 +215,7 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
 5. **Re-publish** each updated post (PATCHing a published post makes it unpublished):
    ```
-   <prefix>CallWixSiteAPI: POST /blog/v3/draft-posts/{draftPostId}/publish
+   REST: POST https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}/publish
    ```
 
    Re-publish calls parallelize — dispatch as concurrent sibling calls.
@@ -236,7 +228,7 @@ The `PATCH /wix-data/v2/items/{itemId}` endpoint exists but requires a JsonPatch
 
 1. Your prompt lists `collections[].itemIds` for each collection with an image field. **Fetch the existing item data** once per collection via `POST /wix-data/v2/items/query` — you cannot skip this step because you need every existing field to merge-preserve.
    ```
-   <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>",
      "query": { "filter": { "_id": { "$in": ["<itemId1>", "<itemId2>", ...] } } }
@@ -250,7 +242,7 @@ The `PATCH /wix-data/v2/items/{itemId}` endpoint exists but requires a JsonPatch
 
 4. **PUT each item's full record** with the image field merged into the existing `data`:
    ```
-   <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": "<collection>",
      "dataItem": {
@@ -269,15 +261,15 @@ body: { "dataCollectionId": "<c>", "dataItem": { "id": "...", "data": { "image":
 ```
 Without the read-merge step, an `about-content` item loses its seeded `heading` and `body` when Image Phase 2 attaches the image — the About page then renders only its fallback copy.
 
-PUT calls parallelize — dispatch all items across all collections as sibling `CallWixSiteAPI` tool calls in one concurrent batch.
+PUT calls parallelize — dispatch all items across all collections as sibling `curl` tool calls in one concurrent batch.
 
-## MCP Tool Prefix
+## REST call discovery
 
-Your prompt includes a `MCP tool prefix:` line. Use it for every Wix MCP call. If a call returns "tool not found", re-discover the tool via your runtime's tool-discovery primitive (look up the suffix `CallWixSiteAPI`). See `../shared/MCP_PREFIX.md` § "Defensive fallback".
+Your prompt includes a `siteId (for token mint):` line. Use it for every Wix REST call. If an endpoint isn't covered by this recipe, fall back to the doc lookup endpoints in `../shared/DOCS_SEARCH.md`.
 
 ## Return Contract
 
-At the end, emit a structured JSON block per `../shared/RETURN_CONTRACT.md`. Do **not** write `.wix/logs/images.md` — sidecars are deprecated; the parent reads your return JSON directly.
+At the end, emit a structured JSON block per `../shared/RETURN_CONTRACT.md`. Do **not** write `.wix/logs/images.md` or any sidecar file; the parent reads your return JSON directly.
 
 ### `image-phase-1-decorative` return
 
@@ -286,14 +278,19 @@ At the end, emit a structured JSON block per `../shared/RETURN_CONTRACT.md`. Do
   "status": "complete" | "partial" | "failed",
   "phase": "image-phase-1-decorative",
   "scope": "image-phase-1-decorative",
-  "summary": "Generated N decorative images; uploaded to Wix Media; wrote .wix/image-urls.md",
+  "summary": "Generated N decorative images; uploaded to Wix Media; returned slot→URL map",
   "data": {
     "decorativeCount": 3,
-    "purposes": ["hero", "about", "background"],
+    "purposes": ["hero", "about", "productsHeader"],
+    "slots": {
+      "hero":  "https://static.wixstatic.com/media/...",
+      "about": "https://static.wixstatic.com/media/...",
+      "productsHeader": "https://static.wixstatic.com/media/..."
+    },
     "model": "google:4@2",
     "totalCredits": 0.297
   },
-  "files": [".wix/image-urls.md"],
+  "files": [],
   "errors": []
 }
 ```
@@ -340,11 +337,11 @@ The JSON block MUST be the **last** content in your message (see `../shared/RETU
 
 | WRONG | CORRECT |
 |-------|---------|
-| N sequential 1-task `CallWixSiteAPI` generation calls across multiple turns | All generation tool calls in one concurrent batch — parallel siblings for `google:4@2`, or one batched call for other models. See IMAGE_GENERATION.md § "Required: minimize round-trips per image phase" |
+| N sequential 1-task `curl` generation calls across multiple turns | Run `generate-images.mjs` (it parallelizes in-process); or, hand-driving, all generation tool calls in one concurrent batch — parallel siblings for `google:4@2`, or one batched call for other models. See IMAGE_GENERATION.md § "Required (manual fallback): minimize round-trips" |
 | Poll `.wix/logs/<feature>-data.md` sidecars to learn Phase 1 Seed is done | Phase 1 Seed data is inline in your prompt — if missing, return `failed` |
 | `sleep 60` loop to wait for Phase 1 Seed | No waiting, no polling — prompt has the data or the agent fails |
-| Write `.wix/logs/images.md` sidecar | Sidecars are deprecated — return structured JSON per `RETURN_CONTRACT.md` |
-| Re-query Phase 1 Seed entity IDs via MCP | IDs are in your prompt; re-querying wastes a round-trip |
+| Write `.wix/logs/images.md` or `.wix/image-urls.md` sidecar | Return structured JSON per `RETURN_CONTRACT.md` instead (decorative URLs go in `data.slots`) |
+| Re-query Phase 1 Seed entity IDs via the REST API | IDs are in your prompt; re-querying wastes a round-trip |
 | Generic prompts ("a product photo") | Use brand context, product name, aesthetic direction |
 | Ignore color palette from prompt | Reference actual hex codes in image prompts |
 | Request text in images | Always include "no text, no watermarks" |
@@ -352,8 +349,9 @@ The JSON block MUST be the **last** content in your message (see `../shared/RETU
 | Use free-form sizes (e.g., `800×600`) | Use allowed dimensions only — `1024×1024`, `1376×768`, `1200×896` |
 | Use blog post `file.url` for cover image | Blog posts need `file.fileUrl` (file ID) for `media.wixMedia.image.id` |
 | Block on image failures | Skip failed images, continue with others |
+| Write any coordination file (`.wix/image-urls.md`, sidecars) | Return slot→URL map in `data.slots`; the orchestrator pipes it to `patch-decorative-slots.mjs` via stdin |
 | PATCH products without `options`/`variantsInfo` | Always query products first for these fields — PATCH returns 428 without them (see § "Products" step 1) |
 | PUT a CMS item with only `{data: {image: "..."}}` | Read-merge-write: query the item, merge image into existing `data`, PUT the full record (see § "CMS Items" step 4). Writing only `image` erases seeded heading/body/etc. |
 | Use `PATCH /wix-data/v2/items/{itemId}` with `{dataItem: {data}}` | PATCH requires JsonPatch `fieldModifications` — use read-merge-PUT instead (see § "CMS Items") |
 | Hit a 428 → immediately search external docs | Re-read § "Products" step 1 first — it covers 428. Only use external docs if your recipe genuinely doesn't cover the error (see § "Self-Loading" step 3) |
-| Default to `ReadFullDocsArticle` for API errors already covered by your recipe | Re-read your own recipe first; fall back to MCP doc tools only for errors genuinely not covered (see § "Self-Loading" step 3) |
+| Default to `raw-docs REST (see DOCS_SEARCH.md)` for API errors already covered by your recipe | Re-read your own recipe first; fall back to the doc-lookup endpoints in `DOCS_SEARCH.md` only for errors genuinely not covered (see § "Self-Loading" step 3) |

package/skills/wix-headless/references/seed-recipes.md

@@ -0,0 +1,49 @@
+# Seed recipe map
+
+Per-vertical recipe lookup for the seed dispatch in `SEED.md`. Recipe paths are **relative to `<wix-manage-root>`**, the absolute path that `wix-manage`'s SKILL.md publishes when Phase 2 Step 4 loads it. The orchestrator joins `<wix-manage-root>` + the relative path at dispatch time. Do not pre-resolve, hardcode, or pre-validate the absolute paths at session start — fail at dispatch time if a recipe has moved.
+
+| Pack | Recipes (relative to `<wix-manage-root>`) | Returns |
+|---|---|---|
+| stores | `references/stores/setup-online-store-catalog-v3.md` (idempotent catalog setup) + `references/stores/bulk-create-products-with-options.md` (single bulk call for N products) | `productIds[]`, `categoryIds[]` (when `intent.stores.categoriesNamed` is non-empty) |
+| cms | `references/cms/cms-schema-management.md` (collection create) + `references/cms/cms-data-items-crud.md` (item create per collection) + `references/cms/cms-references-and-relationships.md` (only when a collection's `intent.cms.collections[N]` declares cross-references) | `collectionIds{}`, `itemIds{<collection>: []}` |
+| blog | `references/blog/how-to-create-blog-posts.md` | `postIds[]`, `categoryIds[]` |
+| forms | `references/forms/create-form.md` | `formIds[]` |
+| gift-cards | — *(no recipe by design — no seed surface; activation lives in Phase 2 app-install)* | `{status: "skipped"}` |
+| ecom | — *(no recipe by design — cart/checkout vertical; no seed surface)* | `{status: "skipped"}` |
+
+The orchestrator dispatches one subagent per pack with a recipe. `gift-cards` and `ecom` get a phase entry of `{phase: "seed-<pack>", status: "skipped"}` recorded directly by the orchestrator without dispatching a subagent.
+
+---
+
+## Per-pack input notes
+
+These notes reduce dispatch-time guesswork. The recipe itself is the source of truth for the API shape — these notes are about how to translate `intent.<pack>` + `brand` into the recipe's input.
+
+### stores
+
+- The bulk recipe wants `products: [{name, slug, sku, price, options?, variants?}]`. Populate `name` and `slug` from `intent.stores.productCount` and `brand` (e.g. for a coffee shop with `productCount: 3`, generate three product names that fit the brand vibe).
+- `sku` defaults to `<slug>-001` when not otherwise constrained.
+- `price` is a positive number; pick brand-appropriate values (don't default to $1).
+- When `intent.stores.categoriesNamed` is non-empty, the subagent creates those categories via the Categories API after the bulk product create and assigns products into them. When the array is empty, skip categories entirely (do not invent a default set).
+- The recipe documents a 5-product cap on the bulk endpoint. If `intent.stores.productCount` exceeds it, fan out into batches of 5.
+- Text-only seeding: do not generate or attach product images. The `media` field follows the recipe's documented placeholder pattern.
+
+### cms
+
+- The schema recipe wants one `POST /wix-data/v2/collections` call per collection in `intent.cms.collections`. Field shape comes from `collection.purpose` — e.g. `purpose: "about"` → a single-row text collection with `title` + `body`; `purpose: "faq"` → repeated `question` + `answer` rows.
+- After all collections exist, the items recipe (`cms-data-items-crud.md`) inserts `intent.cms.collections[N].itemCount` rows per collection, with content generated from `brand`.
+- `cms-references-and-relationships.md` is consulted **only** when a collection's intent block declares cross-references (e.g. `references: ["products"]`). Otherwise skip it.
+- Return shape: `collectionIds: { <purpose>: <id> }` and `itemIds: { <purpose>: [<id>, ...] }`. Keying by `purpose` (not by collection display name) lets Phase 4 wire pages without re-deriving slug ↔ id.
+
+### blog
+
+- The recipe's Part 0 (member ID lookup) is mandatory — third-party app installs require `draftPost.memberId`. The subagent issues one `GET /members/v1/members?paging.limit=1` and uses the returned id for every post.
+- `intent.blog.postCount` posts are created. Topics come from `intent.blog.topics` when present; otherwise the subagent picks brand-appropriate topics from `brand.description`.
+- Text-only seeding: cover images use the recipe's documented placeholder pattern; do not call Media Manager import.
+- `categoryIds[]` returned only when the recipe creates categories during seeding (the recipe handles category-on-create automatically when the post payload references one).
+
+### forms
+
+- One `POST /form-schema-service/v4/forms` call per entry in `intent.forms.forms`. The subagent maps `intent.forms.forms[N].fields` (a string array like `["name", "email", "message"]`) into the recipe's `formFields` payload using the recipe's documented field templates (`CONTACTS_FIRST_NAME`, `CONTACTS_EMAIL`, etc.).
+- `purpose` ("contact", "lead", "signup") drives the form's `name` field — e.g. `"contact"` → `"Contact Form"`.
+- Wix Forms app is usually pre-installed via Phase 2 — the recipe notes this and the seeder does not need to install it again.

package/skills/wix-headless/references/shared/AGENTS_MD.md

@@ -0,0 +1,47 @@
+# AGENTS.md — the end-of-run site doc
+
+The orchestrator writes one file at the end of a successful run: a project-root `AGENTS.md` describing **what the site has**. It is the one end-of-run artifact — *content about the site*, not telemetry. A fresh session (or a coding agent) opening the project reads it to learn what's there.
+
+## Author, location, timing
+
+- **Author:** the orchestrator, in the final turn. Composed **from session scratch** (brand, frontend, verticals, the page/route list it built) **+ `.wix/seeded.json`** (entity counts). **Re-read nothing** to compose it.
+- **Location:** project-root `AGENTS.md` — the conventional path agents auto-read. Root, not `.wix/`. It sits outside the astro/Vite bundler root, so it never ships to `dist/`.
+- **Timing:** the **last tool call of the final message**. Summary prose (the live URL) first; `Write AGENTS.md` last — same ordering discipline `BUILD.md` § "Final Message" defines.
+
+## Content — fill this template, slotted values only
+
+Deterministic projection of scratch + seeded counts → same inputs produce a byte-identical file. Emit exactly these sections; no free prose beyond the slots.
+
+```markdown
+# <brand>
+
+A Wix headless site built with the `wix-headless` skill. <one-line brand description>.
+
+## Live site
+- **Site:** <published URL>
+- **Dashboard:** https://manage.wix.com/dashboard/<siteId>
+
+## Frontend
+<astro (Wix-hosted) | custom>. Run: `<wix dev | npm run dev>`. Build + publish: `<wix release | npm run build then wix release>`.
+
+## Features
+- <one bullet per loaded, non-disabled vertical, in plain language>
+  Stores → a product catalog · CMS → content collections (About, FAQ, …) · Blog → posts · Forms → a contact form · Gift cards → activate from the dashboard
+
+## Pages
+<one line per route that exists: `/`, `/products`, `/products/[slug]`, `/cart`, …>
+
+## Seeded content
+<counts only: "3 products across 2 categories · 6 blog posts · About + FAQ collections.">
+
+## Extending
+Built with the `wix-headless` skill; re-run it to add features or restyle.
+```
+
+## Excluded — never in AGENTS.md
+
+No per-phase timings, statuses, `started`/`ended`/`seconds`, `x-wix-request-id`s, error codes, subagent handles, recoveries, or rate-limit notes. If a field would only matter to someone debugging the *run*, it does not belong here. (Entity IDs stay in `.wix/seeded.json`, not here — counts only.)
+
+## Not a state file
+
+`AGENTS.md` is reading material. Project **detection** ("is this a wix-headless project / which frontend") keys off `wix.config.json` + the `@wix/astro` dep in `package.json` — never `AGENTS.md` presence.