@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -1,357 +0,0 @@
----
-name: images-agent
-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. 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.
-
-## Scope Routing
-
-Your prompt includes `Scope: <name>`. Map it to an image phase:
-
-| 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/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 `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
-   - **400** `"Expected an object"` from product PATCH → missing `revision` → see § "Products" step 4
-   - **400** `unsupportedParameter` → strip `steps`/`CFGScale` → see § "Error Handling"
-   - **400** `unsupportedDimensions` → see § "Error Handling"
-   - **400** `invalidTaskUUID` → `taskUUID` must be valid UUIDv4 → see § "Quick Reference"
-
-## Preferred: generate + import via `generate-images.mjs`
-
-**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.
-
-## Quick Reference: Generation Call Shape (manual fallback)
-
-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):
-
-```
-REST: POST https://www.wixapis.com/runwareschemaless/v1/request
-body: [
-  {
-    "taskType": "imageInference",
-    "taskUUID": "550e8400-e29b-41d4-a716-446655440000",
-    "outputType": "URL",
-    "outputFormat": "PNG",
-    "positivePrompt": "<prompt-for-image>",
-    "height": 1024,
-    "width": 1024,
-    "model": "google:4@2",
-    "numberResults": 1
-  }
-]
-```
-
-Extract `data[i].imageURL` from each response. Import each to Wix Media immediately. **Do NOT send `steps` or `CFGScale`** with `google:4@2` — both cause a 400 error. `taskUUID` must be a valid UUIDv4 (`uuidgen` or `crypto.randomUUID()`) — Runware rejects human-readable slugs with `400 invalidTaskUUID`.
-
-### Mandatory pre-call procedure — construct ALL tasks FIRST, then dispatch in ONE message
-
-Image Phase 2 serializes into 6+ sequential calls across multiple turns when you compose and send tasks one-at-a-time. The fix is to build the full task set first and dispatch them as a single concurrent batch.
-
-**Required procedure (do this, exactly, every time):**
-
-1. **Plan all image prompts in your text response FIRST.** Write out every entity you need to generate for, with its prompt text, dimensions, and UUIDv4. Use a numbered list or table. Do not start any tool calls yet.
-
-2. **Compose the full task set** as a fenced JSON block in your text. Verify the count matches the entity count.
-
-3. **Dispatch in one concurrent batch.** For `google:4@2`: N concurrent sibling calls, each with one task. For other models: one tool call with all N tasks in `body`.
-
-4. **After generation returns:** make all N import calls as **sibling calls in one concurrent batch** (not sequential messages). Same for PATCH calls — all N as siblings in one message.
-
-That gives you exactly 3 concurrent batches for the whole image phase: 1 generate dispatch, 1 batch of imports, 1 batch of PATCHes.
-
-Concurrent siblings are safe across all three stages (gen, import, PATCH). Wix Media imports do not rate-limit at typical scales (≤10/run); product PATCHes against distinct entity IDs do not produce revision conflicts because each entity has independent revision tracking. The 3-message recipe (one batch per stage) typically completes in ~190 s end-to-end vs ~480 s for the same 4 entities done sequentially — ~2.5× speedup.
-
-**Self-check before the generate dispatch:**
-- [ ] You have planned all N tasks with UUIDv4 `taskUUID` values
-- [ ] All generate tool calls will be in one concurrent batch (siblings for `google:4@2`, or one block with N tasks for other models)
-- [ ] You wrote out the full plan in your text before making any tool call
-
-### Expected tool-call budget
-
-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` (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/astro/designer/INSTRUCTIONS.md` § common rule #7); the two must agree.
-
-**Inputs (from your prompt):**
-- Brand name, business type, aesthetic direction
-- Color palette (hex codes)
-- `decorativeSlots: string[]` — the exact slot keys to generate (REQUIRED). If absent, return `status: "failed"` with `reason: "decorativeSlots not provided in prompt"` rather than guessing.
-- Page list (context only — slot keys are authoritative)
-
-**Process (must follow this order):**
-
-1. **Craft all image prompts up front** using brand context — see `IMAGE_GENERATION.md` § "Prompt guidelines".
-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.
-
-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` (Phase 1 Seed data inline)
-
-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.
-
-**Phase 1 Seed entity IDs are in your prompt, not on disk.** Your parent passes a `Phase 1 Seed return data:` block containing:
-- `products: [{id, name, slug, variantId, ...}, ...]` — if stores pack loaded
-- `collections: [{name, itemIds, fields}, ...]` — if cms pack loaded
-- `blogPosts: [{id, title, ...}, ...]` — if blog pack loaded
-
-**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. **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** (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.
-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 `curl` tool calls in one message).
-
-### Products (if `products` is in your prompt)
-
-1. Entity IDs come from your prompt's `Phase 1 Seed return data.products[].id`. Do NOT re-query products for slugs/names (already inline).
-
-   > **428 prevention (MANDATORY):** You MUST fetch each product's existing `options` and `variantsInfo` before step 4. The Update Product endpoint validates variant-option alignment on every PATCH and **returns 428 if either is missing**.
-
-   > **Critical:** `POST /stores/v3/products/query` does **NOT** return `variantsInfo` — even when you pass `fields: [VARIANT_OPTION_CHOICE_NAMES, MERCHANT_DATA, MEDIA_ITEMS_INFO]`. It returns `options` only. Using the bulk-query endpoint produces 428 on every product with variants. Use per-product GETs.
-
-   > **Use per-product GET instead of bulk query:**
-   > ```
-   > 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 `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.
-
-2. Generate images — ONE batched generation call with N tasks (one per product).
-
-3. Import each to Wix Media — parallelize with sibling calls.
-
-4. PATCH each product with its image + preserved options/variantsInfo + product `revision`:
-   ```
-   REST: PATCH https://www.wixapis.com/stores/v3/products/{productId}
-   body: {
-     "product": {
-       "revision": "<product.revision from step 1's GET>",
-       "media": {
-         "itemsInfo": {
-           "items": [
-             { "url": "<wixstatic-url>", "altText": "<product name or short description>" }
-           ]
-         }
-       },
-       "options": <existing options from product query>,
-       "variantsInfo": <existing variantsInfo from product query>
-     }
-   }
-   ```
-   **`revision` is mandatory** — omitting it returns `400 "Expected an object"` with no useful hint. Read it from each product's GET response in step 1 and echo it back on the PATCH. Do NOT use `media.main.image` — `media.itemsInfo.items[].url` is the write-shape; `media.main.image` is the read-shape on product responses (they are asymmetric).
-
-   **DO NOT add `fieldMask` to this PATCH.** The endpoint runs cross-field validation (options ↔ variants) BEFORE applying the field mask, so even though `fieldMask: { paths: ["media"] }` should "only update media", the validator sees variants without options and returns 428 `MISSING_VARIANT_OPTION`. Send the full product body shown above (id, revision, media, options, variantsInfo) and let the server merge — no fieldMask.
-
-   PATCH calls parallelize — dispatch as concurrent sibling calls. Parallel PATCHes against different product IDs do NOT cause revision conflicts: each entity has independent revision tracking.
-
-   **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: `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.
-
-### Blog Posts (if `blogPosts` is in your prompt)
-
-1. Entity IDs come from `Phase 1 Seed return data.blogPosts[].id` in your prompt. Title / excerpt for image context come from the prompt too. No re-query needed unless you need fields not in the return.
-
-2. Generate images — ONE batched generation call with N tasks.
-
-3. Import to Wix Media — save the **`file.fileUrl`** (file ID), not the full URL.
-
-4. PATCH each draft post's cover image:
-   ```
-   REST: PATCH https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}
-   body: {
-     "draftPost": {
-       "media": { "wixMedia": { "image": { "id": "<file-id-from-fileUrl>" } } }
-     }
-   }
-   ```
-
-5. **Re-publish** each updated post (PATCHing a published post makes it unpublished):
-   ```
-   REST: POST https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}/publish
-   ```
-
-   Re-publish calls parallelize — dispatch as concurrent sibling calls.
-
-### CMS Items (if `collections` is in your prompt)
-
-Key constraint: `wix-data/v2/items` updates are **full-record replaces** (via PUT). Writing only `{data: {image: "..."}}` **erases every other field** on the item — heading, body, question, answer, anything the CMS seeder populated. You MUST read the existing item first and merge the image field into its `data` before writing.
-
-The `PATCH /wix-data/v2/items/{itemId}` endpoint exists but requires a JsonPatch-shaped `fieldModifications` array, not a plain `{dataItem: {data}}` body. Do NOT use PATCH for this scope — it has rejected the documented shape in production and led agents to fall back to a destructive PUT. Use read-merge-PUT instead.
-
-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.
-   ```
-   REST: POST https://www.wixapis.com/wix-data/v2/items/query
-   body: {
-     "dataCollectionId": "<collection>",
-     "query": { "filter": { "_id": { "$in": ["<itemId1>", "<itemId2>", ...] } } }
-   }
-   ```
-   Retain the full `data` object from each result — you'll merge into it.
-
-2. Generate images — ONE batched generation call with N tasks across all applicable items.
-
-3. Import to Wix Media.
-
-4. **PUT each item's full record** with the image field merged into the existing `data`:
-   ```
-   REST: PUT https://www.wixapis.com/wix-data/v2/items/{itemId}
-   body: {
-     "dataCollectionId": "<collection>",
-     "dataItem": {
-       "id": "{itemId}",
-       "data": { ...existingData, "<imageField>": "<wixstatic-url>" }
-     }
-   }
-   ```
-   `...existingData` MUST include every non-system field you read in step 1 (`heading`, `body`, etc.). System fields (`_id`, `_owner`, `_createdDate`, `_updatedDate`) don't need to be echoed back — Wix repopulates them.
-
-**Failure mode — do NOT ship with this pattern:**
-```
-// WRONG — wipes heading + body
-PUT /wix-data/v2/items/{itemId}
-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 `curl` tool calls in one concurrent batch.
-
-## REST call discovery
-
-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` or any sidecar file; the parent reads your return JSON directly.
-
-### `image-phase-1-decorative` return
-
-```json
-{
-  "status": "complete" | "partial" | "failed",
-  "phase": "image-phase-1-decorative",
-  "scope": "image-phase-1-decorative",
-  "summary": "Generated N decorative images; uploaded to Wix Media; returned slot→URL map",
-  "data": {
-    "decorativeCount": 3,
-    "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": [],
-  "errors": []
-}
-```
-
-### `image-phase-2-entity` return
-
-```json
-{
-  "status": "complete" | "partial" | "failed",
-  "phase": "image-phase-2-entity",
-  "scope": "image-phase-2-entity",
-  "summary": "Generated + attached images: 6 products, 1 CMS item",
-  "data": {
-    "entityCount": { "products": 6, "cmsAboutContent": 1, "blogPosts": 0 },
-    "model": "google:4@2",
-    "totalCredits": 0.693
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-The JSON block MUST be the **last** content in your message (see `../shared/RETURN_CONTRACT.md` § "Observed failure mode").
-
-## Error Handling
-
-| Error | Action |
-|---|---|
-| `unsupportedParameter` (400) | Strip `steps`/`CFGScale` (or whichever field the response names) and retry once |
-| `unsupportedDimensions` (400) | Retry with `1024×1024` / `1376×768` / `1200×896`, or a value from the error payload's supported list |
-| 428 from product PATCH | Missing `options`/`variantsInfo` — re-read § "Products" step 1; query the product for existing `options` + `variantsInfo`; retry PATCH with those fields included. This recipe covers it — do not look up external docs. |
-| 400 `"Expected an object"` from product PATCH | Missing `revision` in the `product` body — re-read § "Products" step 4; the PATCH body needs `"revision": "<product.revision from step 1 GET>"`. |
-| 400 `invalidTaskUUID` from Runware | `taskUUID` must be valid UUIDv4. Regenerate with `uuidgen` / `crypto.randomUUID()` and retry. |
-| Model unavailable / rate limited | Switch to an alternative model (`bfl:5@1`, `runware:400@1`) and retry once; skip if still failing |
-| Credit exhaustion | Stop generating, return `status: "partial"` with `data.decorativeCount` / `data.entityCount` listing what was completed, and `errors: [{code: "CREDITS_EXHAUSTED", message: "..."}]` |
-| Generation fails (5xx, timeout) | Skip this image, continue with others |
-| Wix Media import fails | Skip this image, continue |
-| Entity PATCH fails | Log the failure in `errors`, continue with other entities |
-| Phase 1 Seed data missing from prompt (Image Phase 2 only) | Return `status: "failed"` immediately; do not poll or re-query |
-
-**Never block other agents on image failures.** Products, posts, and pages work without images.
-
-## Anti-Patterns
-
-| WRONG | CORRECT |
-|-------|---------|
-| 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` 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" |
-| Send `steps` or `CFGScale` with `google:4@2` | Omit both — `google:4@2` rejects them with `unsupportedParameter` |
-| 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 `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

@@ -1,49 +0,0 @@
-# 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

@@ -1,47 +0,0 @@
-# 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.

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

@@ -1,108 +0,0 @@
-# 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"}
-```
-
-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
-
-**Re-mint is never a recovery step — see Token minting.** 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-create.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).

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

@@ -1,8 +0,0 @@
-# Build-output noise — known false positives
-
-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.