@wix/agent-skills 1.5.0 → 1.7.0

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
@@ -38,17 +38,17 @@ If your prompt is missing a `Scope:` line, stop and ask the parent — do not gu
 
 ## Quick Reference: Generation Call Shape
 
-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.
+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/commands/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.
 
 **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:
 
-- **`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.
+- **`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 +93,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
@@ -109,24 +109,15 @@ Generate site-wide decorative images that don't depend on any entity. Used by th
 
 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
+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.
 
-   ## hero
-   - url: https://static.wixstatic.com/media/...
+The orchestrator runs `patch-decorative-slots.mjs` with your `data.slots` map piped in on stdin. The patch script injects `<img>` tags into the designer's `data-decorative-slot="<key>"` placeholders. If your return is missing or has no slots, the patch is a no-op and the placeholders fall back to the designer's solid-color rendering — nothing blocks.
 
-   ## 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.
+## Scope: `image-phase-2-entity` (Phase 1 Seed data inline)
 
-## Scope: `image-phase-2-entity` (Step 4.5 — 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,13 +126,13 @@ 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 `google:4@2` (default): N parallel sibling `curl` 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.
 
@@ -149,7 +140,7 @@ Generate images for products, blog posts, and CMS items. Attach via MCP PATCH ca
 
    **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.)
 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 +152,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 +164,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,7 +188,7 @@ 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.
 
@@ -213,7 +204,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 +214,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 +227,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 +241,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 +260,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 +277,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"],
+    "slots": {
+      "hero":  "https://static.wixstatic.com/media/...",
+      "about": "https://static.wixstatic.com/media/...",
+      "background": "https://static.wixstatic.com/media/..."
+    },
     "model": "google:4@2",
     "totalCredits": 0.297
   },
-  "files": [".wix/image-urls.md"],
+  "files": [],
   "errors": []
 }
 ```
@@ -340,11 +336,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 | 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" |
 | 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 +348,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 seed surface; activation lives in Phase 2 app-install) | `{status: "skipped"}` |
+| ecom | — (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/AUTHENTICATION.md

@@ -0,0 +1,110 @@
+# Authentication
+
+Every Wix API call this skill makes goes through `@wix/cli` + `curl` — no MCP, no SDK. This file documents the auth shape (header layout, token minting, recovery ladder) so individual phase docs don't have to repeat it.
+
+## Prerequisites
+
+- `@wix/cli` resolvable via `npx`. The scaffold installs it project-local, so `npx @wix/cli …` works without a global install.
+- An authenticated CLI session. Test with `npx @wix/cli@latest whoami` — exits **0** when logged in (prints the authenticated email + user id), **non-zero** when logged out.
+
+The primary place this check runs is DISCOVERY.md § "Pre-flight" — foreground, before any `AskUserQuestion`. `scaffold.sh` repeats the check defensively for its standalone-invocation path. **If the check fails, run `npx @wix/cli@latest login` yourself with `run_in_background: true`** per the next section — do not tell the user "run wix login and retry" and stop. Punting to the user breaks the flow: the harness backgrounds the user-issued command, the agent doesn't know which output file to read, and you end up paying ~60 s + a manual user interrupt to recover.
+
+The "stop and tell the user" path is a **last-resort fallback** for when the background-run mechanism itself is broken (e.g. the harness rejects `run_in_background: true`, or the task output file never gets created). Try the agent-driven flow first.
+
+## `wix login` from a non-interactive agent
+
+`wix login` (or `npx @wix/cli@latest login`) emits one JSON event per line on **stdout** and blocks until the human finishes the browser step. The first event you care about is `awaiting_user`:
+
+```json
+{"event":"awaiting_user","expiresInSeconds":600,"userCode":"TPV5HUG5","verificationUri":"https://users.wix.com/login/device-login?color=developer&studio=true"}
+```
+
+(Earlier revisions of this doc claimed the CLI wrote human-readable prose to stderr with no JSON events — that was wrong. The events are JSON on stdout. There may be incidental Node warnings interleaved; line-by-line JSON parsing with a `try` around each line handles that cleanly.)
+
+### How to invoke — exact shape
+
+The Bash command is just the CLI invocation, **nothing else**:
+
+```bash
+npx @wix/cli@latest login
+```
+
+Pass `run_in_background: true` on the Bash tool call. **Do not** add shell `&`, **do not** redirect to your own `mktemp` file, **do not** chain with `echo`/`sleep`. The harness wraps the process for you and writes stdout+stderr to its own task output file at `/tmp/claude-<uid>/<project>/tasks/<task-id>.output`. The tool's `<bash-stdout>` reply gives you that path verbatim — that's the file you read. Stacking shell `&` on top of `run_in_background` creates two layers of backgrounding: the harness captures only the parent shell's `pid:` / `file:` echoes while wix-login's actual JSON events write somewhere else.
+
+### Reading the output
+
+Poll the harness's task-output file until the `awaiting_user` JSON line appears. Use `Read` on the path returned in `<bash-stdout>` — `TaskOutput` also works. The first useful event is on line 1 (a Node `TimeoutNaNWarning` may follow on lines 3-5; ignore it, the agent only cares about the JSON line). Parse the JSON, extract `verificationUri` + `userCode`.
+
+### The critical step: surface, don't re-invoke
+
+When you see the `awaiting_user` event:
+
+1. **Surface URL + code to the user in plain prose. Send the message. Do not write more Bash. Do not re-invoke wix-login "to do it properly this time".** Seeing the `awaiting_user` event means the first invocation is working correctly — reading its output is the right next step. Restarting wix-login throws away the live device-login session and the second instance has nothing to wait for (the user never sees the new code because by the time it's emitted, you've already messaged them the first one or are mid-restart). One invocation, one read, one message, one wait.
+2. The message shape:
+
+   > *"You need to authenticate with Wix. Open `<verificationUri>` in your browser and enter the code `<userCode>` — I'll continue once you've completed the login."*
+
+3. **Then wait** for the harness `task-notification` with `<status>completed</status>`. That's the terminal signal that the wix-login process exited (the user finished the browser flow). Do not re-run `whoami` in a sleep loop while waiting; the notification is the only signal you need.
+
+On `<status>completed</status>` with exit 0, run `whoami` once to confirm and proceed. On non-zero exit (rare — typically a timeout if the user took >600 s, or a network error), surface the tail of the output file to the user and stop.
+
+## Token minting
+
+```bash
+SITE_ID="<siteId>"  # from wix.config.json after scaffold
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")
+```
+
+- Mints a **site-scoped REST token**. **Mint it exactly once per run and never re-mint.** The CLI returns a **byte-identical** token on every call within a run (it caches internally), so re-minting buys nothing — it only costs ~1.25 s of CLI startup per call. Cache the value in session scratch and inline it into every `curl`. This holds on errors too: a re-minted token is the same string and will produce the same result, so re-minting is never a useful reaction to a failed call (the one exception is after a fresh `wix login`, which establishes a new CLI session — see the recovery ladder).
+- Use `npx @wix/cli@latest token …` rather than bare `wix token …`. `@wix/cli` may not be globally installed in every harness; `npx` resolves the project-local copy the scaffold produced. The first invocation auto-fetches the CLI (~3–5 s) if missing; subsequent calls are instant.
+- The first `--site "$SITE_ID"` invocation in a run is the source of truth for `SITE_ID`. Bind it in session scratch; do not re-derive from `wix.config.json` mid-run.
+
+## REST call shape
+
+Every call against `wixapis.com` uses two headers:
+
+```bash
+curl -sS -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required. Variants (`Authorization: $TOKEN`, lowercase `bearer`) are not accepted by all endpoints; standardising on `Bearer` avoids the per-endpoint guessing game.
+- **`wix-site-id: $SITE_ID`** — required by site-scoped REST families (Stores v3, CMS v2, Blog v3, Forms v4, Categories v1, Apps-Installer v1, etc.). Harmless on the few endpoints that don't read it, so include it on every call by default rather than discovering its absence via a 403.
+- **`Content-Type: application/json`** — required on every POST/PATCH body. The CLI token does not set it.
+
+The body is the recipe's documented JSON payload, with `siteId` inlined where the recipe documents it as a field. Wrapper fields from MCP-era recipes (`reason`, `sourceDocUrl`, `siteId` as an outer arg) are not part of the REST shape and drop on the floor.
+
+## Recovery ladder
+
+**Do not re-mint the token as a recovery step** (see token-minting note above — a re-minted token is byte-identical). Retry the *same* call with the *same* cached token.
+
+| Symptom | First response | If it still fails |
+|---|---|---|
+| `401 Unauthorized` | Retry the same call once with the cached token. | The CLI session expired — run `wix login` per the flow above (that establishes a *new* session, so the token minted afterward genuinely differs). Re-minting without a fresh login returns the same expired-context token and will not help. |
+| `403 Forbidden` | Retry the same call once. | The token shape is fine but the caller lacks the permission. The two real causes: (a) the relevant app is not installed yet (re-check `apps-installer-service` returned 200 for that app in Setup Step 4a), (b) the resource requires a provisioning step the recipe doesn't run. Surface the response body; do not loop on retries. |
+| `404 Not Found` on a documented URL | Re-read the recipe — URL path segments are easy to typo (e.g. `/blog/v3/bulk/draft-posts/create`, **not** `/blog/v3/draft-posts/bulk/create`). | Recipe bug; surface and stop. |
+
+**Do not** spend turns A/B-testing the header shape (Bearer vs no-Bearer, with/without `wix-site-id`) or cycling tokens. The shape above is the contract; if a single retry with the cached token doesn't fix it, the issue is upstream and recipe-level debugging will not recover it.
+
+## Account-scoped calls
+
+`npx @wix/cli@latest token` (no flags) mints an **account-scoped** token. `npx @wix/cli@latest token --site "$SITE_ID"` mints a **site-scoped** token. The CLI's `--site` flag is what toggles between the two scopes; there is no separate `--account` flag because omitting `--site` is itself the account-scoped form.
+
+The account-scoped token authenticates against `manage.wix.com` endpoints (e.g. `POST /credit-transactions/v1/credit-transactions/get-account-balance`).
+
+```bash
+# Account-scoped — for /credit-transactions, /accounts, /subscriptions, etc.
+ACCOUNT_TOKEN=$(npx @wix/cli@latest token)
+
+# Site-scoped — for everything site-operating (apps install, products, blog, cms, …)
+SITE_TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")
+```
+
+**Do not share tokens across scopes.** Site-operating calls (`wixapis.com/stores/v3/...`, `/blog/v3/...`, `/wix-data/v2/...`) need the **site** token + `wix-site-id` header; using the account token returns `403 SITE_TOKEN_REQUIRED`. Account-level calls (`manage.wix.com/credit-transactions/...`, `/subscriptions/...`) need the **account** token alone — no `wix-site-id` header; using the site token returns `403 ACCOUNT_TOKEN_REQUIRED`.
+
+Today the only account-scoped call in the skill is the Discovery Q3 balance lookup (`DISCOVERY.md` § 2.5.2). If a future phase needs another, mint a fresh account token at the call site (do not cache across the run alongside the site token — keep them in separate scratch slots so misuse is hard).
+
+**Historical note.** Earlier revisions of this file said the CLI did not expose an account-scoped primitive and concluded the balance lookup was unrecoverable. That was a misreading of `wix token --help` — the help output reads `Get a site-scoped access token` against `--site`, implying (correctly) that omitting `--site` returns the default, account-scoped token. The balance lookup was disabled for no good reason for several runs.

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

@@ -1,8 +1,8 @@
 # Build-output noise — known false positives
 
-Read this only if `npx @wix/cli build` surfaces warnings or errors and you're trying to decide whether they're real. A clean build emits a few warnings that are NOT real failures:
+Read this only if `npx @wix/cli@latest build` surfaces warnings or errors and you're trying to decide whether they're real. A clean build emits a few warnings that are NOT real failures:
 
 - **`Astro.request.headers used on prerendered page`** — emitted by the `@wix/astro` integration's middleware on every prerendered route. Internal to the integration, not from skill-emitted code. Ignore.
 - **`Failed to resolve dependency: @wix/stores, present in client 'optimizeDeps.include'`** — Vite warning. The integration speculatively lists `@wix/stores` in `optimizeDeps` regardless of whether the project depends on it. Harmless.
 
-Do NOT add filters, edit config, or attempt to silence these — they're upstream and stable. Surface to the user only if a real build failure needs context.
+Do NOT add filters, edit config, or attempt to silence these — they're upstream and stable. Surface to the user only if a real build failure needs context.

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

@@ -0,0 +1,41 @@
+# Wix documentation lookups
+
+Operational calls in this skill use `npx @wix/cli@latest token --site "$SITE_ID"` + `curl` against `wixapis.com` (see `AUTHENTICATION.md`). When a bundled recipe falls short and you need to look up an endpoint, method schema, or article body, use the public unauthenticated REST endpoints below. **No MCP, no SDK** — these are plain `curl` calls.
+
+## Doc search
+
+| Need | Endpoint |
+|---|---|
+| Search REST / SDK / headless docs | `GET https://www.wixapis.com/mcp-docs-search/v1/search?kbName=<KB>&searchTerm=<q>&maxResults=<n>` |
+| Read a full article | `GET https://dev.wix.com/rawdocs/api/get-article-content?articleUrl=<url>&schema=false` |
+| Read method schema | Same URL with `schema=true` |
+| Browse REST docs menu | `GET https://dev.wix.com/docs/api/v1/get-menu-content?url=<url>&format=markdown` |
+
+**kbName values** (common): `REST_METHODS_KB_ID`, `SDK_KB_ID`, `HEADLESS_KB_ID`.
+
+Example — search REST docs for app install:
+
+```bash
+curl -sS --get 'https://www.wixapis.com/mcp-docs-search/v1/search' \
+  --data-urlencode 'kbName=REST_METHODS_KB_ID' \
+  --data-urlencode 'searchTerm=install app instance' \
+  --data-urlencode 'maxResults=3'
+```
+
+Example — fetch article body:
+
+```bash
+curl -sS --get 'https://dev.wix.com/rawdocs/api/get-article-content' \
+  --data-urlencode 'articleUrl=https://dev.wix.com/docs/...' \
+  --data-urlencode 'schema=false'
+```
+
+No auth headers required on these endpoints.
+
+## Prefer bundled references
+
+Your skill directory includes `.md` reference files with API recipes and error handling for your scope. **Read those first.** Use the doc endpoints above only when you hit an error or endpoint not covered by the bundled recipe — each external doc read costs a tool call and 15–30 s.
+
+## Absolute paths
+
+Subagents run with the **project directory** as CWD, not the skill root. Every dispatch prompt must include `Instruction file (absolute path): <SKILL_ROOT>/references/<scope>/INSTRUCTIONS.md`. Read that path only; use the absolute sibling paths it lists. Never resolve `references/...` against the project CWD.

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

@@ -1,15 +1,15 @@
 # Recipe: AI Image Generation + Wix Media Import
 
-Generate images using **Wix AI (Runware)** via the Wix MCP, then import them into Wix Media. This is a **pure utility** — it generates an image and returns the result. The calling skill owns prompt construction and entity attachment.
+Generate images using **Wix AI (Runware)** via the `wixapis.com` REST proxy, then import them into Wix Media. This is a **pure utility** — it generates an image and returns the result. The calling skill owns prompt construction and entity attachment.
 
-Image generation is MCP-authenticated — no API keys, no curl, no sandbox escape hatches. Runs automatically whenever the image agent launches.
+Image generation authenticates with the same CLI-minted site-scoped token used for every other Wix REST call in this skill (see `AUTHENTICATION.md`) — no separate API keys, no MCP, no sandbox escape hatches.
 
 ## Step 1: Generate Image via Wix AI
 
-Call the Runware proxy through `CallWixSiteAPI`. The body is an **array of tasks** — one request can generate N images by adding more task objects.
+Call the Runware proxy through `curl`. The body is an **array of tasks** — one request can generate N images by adding more task objects.
 
 ```
-CallWixSiteAPI: POST https://www.wixapis.com/runwareschemaless/v1/request
+REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 body: [
   {
     "taskType": "imageInference",
@@ -25,7 +25,7 @@ body: [
 ]
 ```
 
-Before the first call, ensure the `CallWixSiteAPI` tool schema is loaded (the orchestrator's Step 0 MCP bootstrap covers this — see `<SKILL_ROOT>/references/commands/mcp-bootstrap.md`) so `body` is sent as a real JSON array (not a stringified blob). Use your runtime's tool-discovery primitive if you need to (re-)load it.
+Before the first call, ensure the `curl` tool schema is loaded (the orchestrator's session auth covers this — see `<SKILL_ROOT>/references/commands/AUTHENTICATION.md`) so `body` is sent as a real JSON array (not a stringified blob). Use your runtime's AUTHENTICATION.md recovery ladder if you need to (re-)load it.
 
 Extract `data[0].imageURL` from the response. This is a short-lived URL — **import to Wix Media immediately** in the same task queue.
 
@@ -65,7 +65,7 @@ The image agent's `image-phase-1-decorative` and `image-phase-2-entity` scopes e
 ### For `bfl:5@1`, `runware:400@1`, and other models: ONE batched call
 
 ```
-<prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request
+REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 body: [
   { "taskType": "imageInference", "taskUUID": "<uuid-1>", "positivePrompt": "...", ... },
   { "taskType": "imageInference", "taskUUID": "<uuid-2>", "positivePrompt": "...", ... },
@@ -76,13 +76,13 @@ One round-trip. Response's `data[]` array contains one result per task, matched
 
 ### For `google:4@2` (the default): N parallel 1-task sibling calls
 
-`google:4@2` times out with `504` when a single request bundles N≥3 tasks — Runware's backend serializes work per request and the model is slow enough that large batches exceed the proxy timeout. Instead, emit **N parallel `CallWixSiteAPI` tool calls as siblings in one concurrent batch**, each carrying one task:
+`google:4@2` times out with `504` when a single request bundles N≥3 tasks — Runware's backend serializes work per request and the model is slow enough that large batches exceed the proxy timeout. Instead, emit **N parallel `curl` tool calls as siblings in one concurrent batch**, each carrying one task:
 
 ```
 Assistant message (single turn, multiple tool calls):
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task1 ]
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task2 ]
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task3 ]
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 ```
 
 All three fire in parallel (runtime dispatches concurrent siblings concurrently). No 504, no sequential wait. The important constraint is *one concurrent batch* — splitting them across turns loses the parallelism and degenerates into the anti-pattern below.
@@ -91,11 +91,11 @@ All three fire in parallel (runtime dispatches concurrent siblings concurrently)
 
 Sequential 1-task calls across multiple turns:
 ```
-Assistant msg 1:  <prefix>CallWixSiteAPI  body: [ task1 ]
+Assistant msg 1:  curl  body: [ task1 ]
 (runtime waits)
-Assistant msg 2:  <prefix>CallWixSiteAPI  body: [ task2 ]
+Assistant msg 2:  curl  body: [ task2 ]
 (runtime waits)
-Assistant msg 3:  <prefix>CallWixSiteAPI  body: [ task3 ]
+Assistant msg 3:  curl  body: [ task3 ]
 ```
 Each turn adds inter-message overhead. Whether you're using the batched pattern or parallel siblings, **all the image-generation tool calls MUST be in one concurrent batch**.
 
@@ -105,7 +105,7 @@ The following procedure prevents the observed serialization anti-pattern. Follow
 
 1. **Write all prompts first.** In your text response, list every image you will generate with its positivePrompt, dimensions, and a UUID. Do not make any tool calls yet.
 2. **Compose the full body array** as a fenced JSON block in your text. Verify the task count matches the entity count.
-3. **One tool call.** Make exactly one `CallWixSiteAPI` call with that complete body array.
+3. **One tool call.** Make exactly one `curl` call with that complete body array.
 4. **Parallel imports.** After the generate response arrives, emit all N `POST /site-media/v1/files/import` calls as **concurrent sibling calls in one concurrent batch**.
 5. **Parallel PATCHes.** After all imports resolve, emit all N PATCH calls as **concurrent sibling calls in one concurrent batch**.
 
@@ -113,7 +113,7 @@ The following procedure prevents the observed serialization anti-pattern. Follow
 
 ### Media import and entity PATCH — parallelize with siblings
 
-Generation is one concurrent batch — whether that's one batched call or N parallel siblings. The follow-up steps (`POST /site-media/v1/files/import` per image, and entity PATCH per product/post/item) are per-entity; those can parallelize via concurrent siblings — emit all N import calls in one concurrent batch, then all N PATCH calls in one concurrent batch. See the skill's `references/ORCHESTRATION.md` § "Batching compliance" for why sibling batching beats sequential dispatch.
+Generation is one concurrent batch — whether that's one batched call or N parallel siblings. The follow-up steps (`POST /site-media/v1/files/import` per image, and entity PATCH per product/post/item) are per-entity; those can parallelize via concurrent siblings — emit all N import calls in one concurrent batch, then all N PATCH calls in one concurrent batch. See the skill's `references/PLAN.md` § "Batching discipline" for why sibling batching beats sequential dispatch.
 
 **Pattern for an image phase:** one batched generation call → N parallel imports (sibling calls in one message) → N parallel PATCHes (sibling calls in one message).
 
@@ -122,7 +122,7 @@ Generation is one concurrent batch — whether that's one batched call or N para
 This API is Wix-side and model-agnostic — the same shape works for any image source:
 
 ```
-CallWixSiteAPI: POST /site-media/v1/files/import
+REST: POST https://www.wixapis.com/site-media/v1/files/import
 body: {
   "url": "<imageURL from Runware response>",
   "mimeType": "image/png",
@@ -182,4 +182,4 @@ Every prompt should incorporate the full brand context available from the discov
 | Wix Media import fails | Skip this image, entity gets no image |
 | All images fail | Proceed without images, return `status: "failed"` with the root cause |
 
-**Never block the main flow on image generation failure.** Products, posts, and pages work without images — users can upload their own via the Wix dashboard later.
+**Never block the main flow on image generation failure.** Products, posts, and pages work without images — users can upload their own via the Wix dashboard later.