@wix/agent-skills 1.0.0

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

@@ -0,0 +1,185 @@
+# 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.
+
+Image generation is MCP-authenticated — no API keys, no curl, no sandbox escape hatches. Runs automatically whenever the image agent launches.
+
+## 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.
+
+```
+CallWixSiteAPI: POST https://www.wixapis.com/runwareschemaless/v1/request
+body: [
+  {
+    "taskType": "imageInference",
+    "taskUUID": "<unique-uuid-per-task>",
+    "outputType": "URL",
+    "outputFormat": "PNG",
+    "positivePrompt": "<PROMPT>",
+    "height": 1024,
+    "width": 1024,
+    "model": "google:4@2",
+    "numberResults": 1
+  }
+]
+```
+
+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.
+
+Extract `data[0].imageURL` from the response. This is a short-lived URL — **import to Wix Media immediately** in the same task queue.
+
+### Required Fields
+
+| Field | Value | Notes |
+|-------|-------|-------|
+| `taskType` | `"imageInference"` | Always this value |
+| `taskUUID` | valid **UUIDv4** | Runware validates the v4 format strictly — human-readable slugs like `product-maestro-001` return `400 invalidTaskUUID`. Generate via `uuidgen` (macOS/Linux) or `crypto.randomUUID()`. Example: `550e8400-e29b-41d4-a716-446655440000`. One unique UUID per task; reusing in the same request errors. |
+| `outputType` | `"URL"` | Return a URL (not base64) |
+| `outputFormat` | `"PNG"` or `"JPG"` | PNG for transparency-friendly art, JPG for photography |
+| `positivePrompt` | brand-contextual prompt | See "Prompt Guidelines" below |
+| `height`, `width` | one of the allowed pairs below | Free-form sizes return 400 |
+| `model` | `"google:4@2"` (default) | Nano Banana Pro 2. Alternatives: `bfl:5@1`, `runware:400@1` — only switch if the default fails repeatedly |
+| `numberResults` | `1` | Increase if you need multiple variants per prompt |
+
+### Allowed Dimensions (safe defaults)
+
+Runware enforces a fixed set per model. Start with these — all three were validated end-to-end this session with `google:4@2`:
+
+| Aspect | Size | Use for |
+|--------|------|---------|
+| Square | `1024 × 1024` | Product photos, decorative squares, Instagram-style hero |
+| 16:9 | `1376 × 768` | Page heroes, wide banners |
+| 4:3 | `1200 × 896` | About-page visuals, editorial imagery |
+
+If a 400 response lists supported dimensions, use one from that list — do not retry with the same invalid size.
+
+### Forbidden Parameters (for `google:4@2`)
+
+Do NOT send `steps` or `CFGScale` — both are rejected with `unsupportedParameter` and cause a 400. These fields are valid for other Runware models but must be omitted for `google:4@2`.
+
+## Required: minimize round-trips per image phase
+
+The image agent's `image-phase-1-decorative` and `image-phase-2-entity` scopes each generate multiple images. **Do not emit N one-task calls in sequential turns** — sequential dispatch across many turns adds ~30–40 s of inter-message overhead. The correct shape depends on the model:
+
+### For `bfl:5@1`, `runware:400@1`, and other models: ONE batched call
+
+```
+<prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request
+body: [
+  { "taskType": "imageInference", "taskUUID": "<uuid-1>", "positivePrompt": "...", ... },
+  { "taskType": "imageInference", "taskUUID": "<uuid-2>", "positivePrompt": "...", ... },
+  { "taskType": "imageInference", "taskUUID": "<uuid-3>", "positivePrompt": "...", ... }
+]
+```
+One round-trip. Response's `data[]` array contains one result per task, matched by `taskUUID`.
+
+### 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:
+
+```
+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 ]
+```
+
+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.
+
+### ANTI-PATTERN (slow, regardless of model)
+
+Sequential 1-task calls across multiple turns:
+```
+Assistant msg 1:  <prefix>CallWixSiteAPI  body: [ task1 ]
+(runtime waits)
+Assistant msg 2:  <prefix>CallWixSiteAPI  body: [ task2 ]
+(runtime waits)
+Assistant msg 3:  <prefix>CallWixSiteAPI  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**.
+
+### Procedure to enforce batching
+
+The following procedure prevents the observed serialization anti-pattern. Follow these steps in order:
+
+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.
+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**.
+
+**Three concurrent batches total (one per stage).** If you find yourself making more, stop and check whether you're serializing.
+
+### 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.
+
+**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).
+
+## Step 2: Import to Wix Media
+
+This API is Wix-side and model-agnostic — the same shape works for any image source:
+
+```
+CallWixSiteAPI: POST /site-media/v1/files/import
+body: {
+  "url": "<imageURL from Runware response>",
+  "mimeType": "image/png",
+  "displayName": "<descriptive-name>.png"
+}
+```
+
+## Returns
+
+The Wix Media import response contains a `file` object. The calling skill receives two values:
+
+| Field | Value | Use For |
+|-------|-------|---------|
+| `file.url` | Full permanent `wixstatic.com` URL | Product media, `<img>` tags, CSS `background-image`, CMS Image fields |
+| `file.fileUrl` | File ID (e.g., `9a9cdf_abc123~mv2.png`) | Blog post `media.wixMedia.image.id` field |
+
+The calling skill is responsible for attaching the image to whatever entity it belongs to (product, blog post, page element).
+
+## Prompt Guidelines
+
+Every prompt should incorporate the full brand context available from the discovery and design phases. Never generate generic images.
+
+### Prompt Structure
+
+1. **Subject** — what the image shows
+2. **Brand aesthetic** — the design direction from brand discovery
+3. **Color guidance** — reference the brand palette (e.g., "warm cream and forest green tones" not generic colors)
+4. **Style/mood** — photography style, lighting, composition
+5. **Constraints** — always include "no text, no watermarks"
+
+### Context Sources
+
+| Source | What to Extract |
+|--------|----------------|
+| Discovery plan | Business type, brand name, industry, target audience |
+| Design Step 1 (brand discovery) | Aesthetic direction, mood, personality |
+| Design Step 2 (design system) | Color palette hex codes from `global.css` |
+| Entity being created | Product name/description, blog post title/topic, page purpose |
+
+### Anti-Patterns (NEVER do these)
+
+- Generic prompts without brand context ("a product photo")
+- Ignoring the color palette established in global.css
+- Using stock-photo language ("diverse team of professionals")
+- Requesting text in images (AI-generated text is garbled)
+- Same prompt style across different brand aesthetics
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| `unsupportedParameter` (400) | Strip the offending field (most commonly `steps` or `CFGScale`) and retry |
+| `unsupportedDimensions` (400) | Retry with one of the allowed defaults (`1024×1024`, `1376×768`, `1200×896`) or a size from the error payload's supported list |
+| Model-specific failure (model down, 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 `errors: [{code: "CREDITS_EXHAUSTED", ...}]` listing what was completed (see `RETURN_CONTRACT.md`) |
+| Generation fails (5xx, timeout) | Skip this image, continue with others |
+| 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.

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

@@ -0,0 +1,155 @@
+# Shared Implementer — Common Behavior for Every Vertical Subagent
+
+This file is **extended by every per-vertical `INSTRUCTIONS.md`** (stores, ecom, cms, blog, forms, gift-cards). Per-vertical instruction files are thin — they declare scopes and reference paths. Everything else lives here.
+
+## Self-loading
+
+Read **only** the files your scope needs. The reading set varies by scope:
+
+| Your scope | Mandatory | Conditional |
+|---|---|---|
+| `seed` | this file, `RETURN_CONTRACT.md`, `MCP_PREFIX.md` | — |
+| `components`, `components-css`, `pages`, `pages-*` | this file, `RETURN_CONTRACT.md`, `STYLING.md` | — |
+| Image scopes | (read `references/images/INSTRUCTIONS.md` § Self-Loading) | — |
+
+Then read the specific reference(s) for your declared scope (see your vertical's `INSTRUCTIONS.md` scope table). Do NOT read references for scopes other than the one named in your prompt — wastes context and blurs ownership.
+
+## Phase routing
+
+Your prompt includes a line `Scope: <name>`. Map to exactly one reference set per your vertical's `INSTRUCTIONS.md` scope table. If the `Scope:` line is missing, stop and ask the parent — do not guess.
+
+Standard scope names (see architecture-proposal §3):
+- `seed` — Seed phase (MCP data setup, no frontend code)
+- `components` — Components phase (reusable React/Astro islands, SDK wiring)
+- `pages` — Pages phase (route files with visual design + data queries, single scope per vertical)
+- `pages-<name>` — Pages phase sub-scope (only when a vertical has multiple pages groups, e.g. stores has `pages-products`, `pages-home-and-nav`)
+
+## MCP tool prefix
+
+Your prompt includes `MCP tool prefix: <prefix>`. Substitute it for `mcp__wix-mcp-remote__` wherever it appears in your reference files. See `references/shared/MCP_PREFIX.md` for discovery rules.
+
+If your scope is `components` or `pages`, you should NOT make MCP calls — those scopes are frontend-only. If you find yourself needing MCP, it's a scope violation — return `status: "partial"` with an error note, do not proceed.
+
+## Reading `.wix/site.json`
+
+Every agent reads `.wix/site.json` at the start of its run. The file is the single source of truth for per-project data:
+
+```jsonc
+{
+  "brand":        { "name": "...", "description": "..." },
+  "seeded":       { "stores": { "products": [...] }, "cms": { "collections": {...} }, ... },
+  "designTokens": { "colors": {...}, "fonts": {...}, "radii": {...}, "spacing": {...} },
+  "verticals":    ["stores", "ecom", "cms"]
+}
+```
+
+**Phase-specific reads:**
+
+| Scope | What to read from site.json |
+|---|---|
+| `seed` | `brand` (for copy generation — product descriptions, FAQ answers). Do NOT read `seeded.<self>` — you're writing it. |
+| `components` | `brand`, `designTokens` (via `var(--color-*)` in CSS). |
+| `pages` / `pages-*` | `brand`, `seeded.<vertical>` (products, posts, collections), `designTokens`. Page data comes from `seeded`, NOT from re-querying MCP. |
+
+If a required key is missing (e.g. `seeded.stores.products` absent when you're dispatched as `pages-products`), fail fast — return `status: "failed"` with `errors: [{ code: "SITE_JSON_INCOMPLETE", missing: "seeded.stores.products" }]`. Do NOT re-query MCP — the data gap means a seeder didn't complete, and re-querying would mask the real bug.
+
+## Seeders write their data for the orchestrator to aggregate
+
+Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The parent skill merges your return into `.wix/site.json.seeded.<vertical>` after your run completes. You do NOT write `site.json` yourself — return the data and let the orchestrator aggregate.
+
+## Writing page files
+
+Pages-phase agents write route files (`.astro`) with:
+
+1. **Visual design via design tokens and Tailwind.** Reference tokens as `var(--color-primary)` in `<style>` blocks or `bg-[--color-primary]` as Tailwind arbitrary values. Use canonical component templates (`agents/<vertical>/templates/*.astro`) as starting points — adapt, don't invent.
+2. **Data queries against seeded data.** Read the seeded entities from `.wix/site.json.seeded.<vertical>` at build time (Astro frontmatter `import { site } from "../../.wix/site"`) or at request time via the SDK if the page is server-rendered.
+3. **Imports from shared components.** Pages import components your Components-phase agent wrote (`src/components/*.tsx`, `.astro`).
+4. **Imports from skill shared utilities.** `from "../utils/wix-image"` and `from "../utils/analytics"` — these are skill-shipped (copied into the project by `seed-utilities.sh` during Setup); do NOT import them from anywhere else.
+
+## Contributing to shared files via markers
+
+When your vertical's pack frontmatter declares `contributes:` entries, you insert at named markers in files created by the Design System phase or another vertical. Example: `Navigation.astro` has `<!-- nav:links -->` and `<!-- nav:actions -->` markers; each vertical inserts at its declared marker.
+
+**How to insert at a marker:**
+
+1. Read the shell file to see current content.
+2. Locate your marker comment (exact string match from your `contributes[].marker`).
+3. Insert your snippet immediately AFTER the marker line. Do NOT remove the marker — other verticals or future runs may still use it.
+4. Preserve the file's other content exactly.
+
+If your marker is missing from the file, fail fast — it means the shell wasn't scaffolded correctly. Do not invent your own insertion point.
+
+### Marker discipline — strict rules
+
+Multiple Phase 4 agents patch the same files concurrently (`Navigation.astro` is touched by stores, ecom, and gift-cards; `index.astro` by stores and gift-cards). To keep their edits compatible:
+
+- **Never delete the marker comment** — even if your insert makes it look redundant, leave the comment in place. Other verticals running in parallel rely on `Edit` finding it.
+- **Edit only between/at YOUR marker.** Do not reorder, deduplicate, or "tidy up" content inserted by another agent — even if it looks duplicated. If you observe a duplicate, return `status: "partial"` with `errors: [{code: "MARKER_CONFLICT", marker: "<name>", detail: "..."}]` rather than self-deciding which copy to keep. Concurrent agents have no shared truth on insert order.
+- **Insert AFTER the marker, never replace it.** Use `Edit` with `old_string` = the marker line and `new_string` = the marker line + a newline + your snippet. Never `Edit` with `old_string` containing both the marker and surrounding content unless you also re-emit the marker verbatim in `new_string`.
+- **If your marker has prior content (designer placed a placeholder), append rather than replace** unless your scope reference explicitly says to clear-and-replace. The designer is instructed not to speculatively populate pack-owned slots, but mistakes happen — appending degrades to a duplicate that the user can clean up; replacing destroys hand-tuned content.
+
+## Shared implementation rules
+
+Three rules recur across verticals and live here as the single source of truth. Per-vertical references cross-link rather than restating.
+
+### SSR error guards (`.astro` frontmatter)
+
+**Every Wix SDK `await` in `.astro` frontmatter MUST be wrapped in try/catch with a safe fallback.** An uncaught throw during render aborts Astro's response stream mid-body — the browser sees HTML up to the failing await and no further (a home page rendering nav + blank body is the typical symptom).
+
+```astro
+---
+let productList: any[] = [];
+try {
+  const result = await productsV3.queryProducts({ fields: ["CURRENCY"] }).limit(50).find();
+  productList = result.items ?? [];
+} catch (err) {
+  console.error("[products] listing query failed:", err);
+}
+---
+```
+
+Safe fallbacks: an empty array, `Astro.redirect("/404")`, or a graceful placeholder. Never let an SDK error crash the page.
+
+### Fire-and-forget analytics
+
+**`trackEvent` calls MUST NOT throw up the call stack and MUST NOT block user-facing flow.** Analytics failures (blocked by adblock, network error, invalid payload) are acceptable; a broken cart add or product click handler is not. Import `trackEvent` from `../utils/analytics` and call it directly — the shared util swallows its own errors. Do not `await` it and do not wrap it in `try/await` expecting it to retry. If a component wraps analytics alongside a business-critical call, put the business call first:
+
+```ts
+await currentCart.addToCurrentCart({ … });
+trackEvent("AddToCart", { … }); // fires after; can't break the cart if it fails
+```
+
+### Styling
+
+The full styling contract (tokens-as-utilities default, when global semantic classes are appropriate, co-located styles for one-offs, the always-required class list) lives in `STYLING.md`. Read it before any `components` / `pages` work — it's the canonical source. Do not reinvent class names; do not duplicate rules across files.
+
+## Style conventions
+
+- **camelCase for identifiers, kebab-case for filenames, PascalCase for components.** Example: `ProductCard.astro`, `queryBlogPosts` function, `cart-updated` event.
+- **No inline styles beyond design-token CSS variables.** `style={{ color: "red" }}` is forbidden; `style={{ color: "var(--color-primary)" }}` is fine.
+- **Tailwind utilities are local to the component.** Don't invent cross-cutting class names. If you need section padding, write `<section class="py-4xl">` — not `<section class="hero-section">`. If you need a flex column with gap, write `class="flex flex-col gap-md"` — not `class="product-card-body"`. If two components need the same look, extract a shared primitive component, not a shared class name. The retained list of legitimate global semantic classes is short and lives in designer `INSTRUCTIONS.md` § "Always-required global semantic classes" — anything outside that list does not belong in `global.css`.
+- **Tailwind v4 `@reference` is mandatory in any scoped CSS that uses `@apply`.** Tailwind v4 isolates `@apply` per file — utilities defined in the main entry CSS (where `@theme` lives) are NOT visible to `components-*.css` unless that file prepends `@reference "./global.css";` on line 1. Without it, `wix cli build` fails with `Cannot apply unknown utility class 'gap-sm' …`. **`tsc` and `astro check` both pass clean** — only the bundler catches the regression. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-sm font-display text-sm`), the file MUST start with:
+  ```css
+  @reference "./global.css";
+  ```
+  Without it, the build breaks at release time even though `tsc` and `astro check` pass clean — only the bundler catches it.
+- **Fail loud, never silently.** If data is missing, a required field is absent, or an MCP call returns an unexpected shape, return `status: "failed"` with details. Do not invent placeholders or swallow errors.
+
+## Return contract
+
+Every agent ends its message with a fenced JSON block per `RETURN_CONTRACT.md`. The JSON MUST be the last content in the message — no trailing prose. Timing fields are NOT included (the orchestrator captures timing via runtime `duration_ms`).
+
+## Common failure modes
+
+| Wrong | Right |
+|---|---|
+| Reading references for scopes other than the declared `Scope:` | Read only your scope's references |
+| Querying MCP from a `components` or `pages` scope | Components/Pages are frontend-only; use `seeded` data from `site.json` |
+| Re-querying when `site.json.seeded.<vertical>` is missing | Fail fast with `SITE_JSON_INCOMPLETE` — the seeder didn't complete |
+| Writing `.wix/site.json` from a seeder | Seeders return data; orchestrator writes site.json |
+| Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-md"`, `class="py-4xl"`). For one-off page decoration, co-located `<style>` block. |
+| Removing a marker after inserting at it | Marker stays; other verticals may contribute after you |
+| Trailing narrative prose after the return JSON | JSON block must be the last content |
+| Fabricated timestamps in the return JSON | Do not include timing fields — orchestrator captures them |
+| Inline `style="color: red"` | Use design tokens: `style="color: var(--color-primary)"` |
+| Creating a new cross-cutting class name | Extract a shared primitive component instead |

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

@@ -0,0 +1,105 @@
+# Wix MCP Tool Prefix — Discovery & Propagation
+
+Wix MCP tools are exposed under one of two prefixes depending on how the user installed the integration:
+
+| Install mode | Prefix |
+|---|---|
+| **Plugin** (typical for end users) | `mcp__plugin_<plugin-name>_wix-mcp-remote__` (e.g. `mcp__plugin_wix-headless_wix-mcp-remote__WixREADME`) |
+| **Direct MCP server** | `mcp__wix-mcp-remote__` (e.g. `mcp__wix-mcp-remote__WixREADME`) |
+
+Tool **suffixes** are identical in both modes: `WixREADME`, `CallWixSiteAPI`, `ListWixSites`, `ManageWixSite`, `SearchWixHeadlessDocumentation`, `SearchWixSDKDocumentation`, `SearchWixRESTDocumentation`, `BrowseWixRESTDocsMenu`, `ReadFullDocsArticle`, `ReadFullDocsMethodSchema`. Only the prefix differs.
+
+Documentation in this plugin uses the canonical short form (`mcp__wix-mcp-remote__<suffix>`) for readability — substitute the discovered prefix at runtime.
+
+---
+
+## Discovery — entry-point skills only, once per session
+
+The entry-point skill (`wix-headless`) MUST run this before any other MCP call:
+
+1. Use whatever tool-discovery primitive your runtime provides to look up `WixREADME`.
+2. From the returned tool name, strip the trailing `WixREADME` — what remains (ending in `wix-mcp-remote__`) is the **MCP prefix**. Examples:
+   - Returned name `mcp__plugin_wix_wix-mcp-remote__WixREADME` → prefix `mcp__plugin_wix_wix-mcp-remote__`
+   - Returned name `mcp__wix-mcp-remote__WixREADME` → prefix `mcp__wix-mcp-remote__`
+3. Call `<prefix>WixREADME` once to verify connectivity.
+4. **If discovery returns no match, or the verify call fails:** stop and tell the user:
+   > *"Wix MCP tools are not available in this session. Please ensure the Wix MCP server is connected (or that the Wix plugin is enabled), then restart your client."*
+5. Hold the discovered prefix in working memory for the rest of the session — use it for every MCP call AND pass it into every subagent prompt.
+
+---
+
+## Propagation to subagents
+
+Subagents (every Phase 1 / Phase 2 / Phase 3 / Phase 4 implementer) are isolated workers — they see only the prompt their parent gave them, not the parent's session state. Every subagent prompt MUST include this line verbatim near the top:
+
+```
+MCP tool prefix: <discovered prefix>
+Use this prefix for every Wix MCP call. Example: <prefix>CallWixSiteAPI, <prefix>WixREADME.
+```
+
+Without this line the subagent will try the canonical short form and fail in plugin mode.
+
+---
+
+## `CallWixSiteAPI` call conventions — read before the first call
+
+`CallWixSiteAPI` is the most error-prone tool in this plugin. Two failure modes recur; avoid both:
+
+**1. Missing required wrapper params.** The tool requires — in addition to `method`, `url`, `body` — these wrapper fields:
+
+- `siteId` — from `wix.config.json` (or the parent prompt)
+- `reason` — one-sentence human reason, e.g. `"Install Wix Stores app for <brand>"`
+- `sourceDocUrl` — the Wix docs URL the recipe is from, e.g. `"https://dev.wix.com/docs/picasso/wix-ai-docs/recipes-v2/manage/platform/recipe-install-wix-apps"`
+
+**2. `body` passed as a stringified JSON.** `body` is typed `anyOf: [object, array]` — pass it as a real structured value. `body: "{\"tenant\":…}"` will be rejected with `Expected object, received string`.
+
+**The safe pattern — follow on the first `CallWixSiteAPI` of each session:**
+
+1. **Load the schema** via your runtime's tool-discovery primitive (the orchestrator's Step 0 already did this for the whole session per `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` — only re-load if you hit a tool-not-found error).
+2. Call with the full shape:
+   ```
+   <prefix>CallWixSiteAPI(
+     siteId: "<siteId from wix.config.json>",
+     reason: "<one-sentence reason>",
+     sourceDocUrl: "<URL of the Wix docs recipe you're following>",
+     method: "POST",
+     url: "https://www.wixapis.com/<service>/<path>",
+     body: { …as a real object, not a string }
+   )
+   ```
+
+**When you see reference snippets written in prose-HTTP form** (e.g. `CallWixSiteAPI: POST /blog/v3/posts` followed by `body: { … }`), translate them into the full tool-call shape above — the prose form omits the wrapper fields for readability, not because they're optional.
+
+## Defensive fallback — required in every implementer agent
+
+If a Wix MCP call returns "tool not found" or the tool name appears unavailable for any reason:
+
+1. Re-discover the tool via your runtime's tool-discovery primitive, looking up the suffix (e.g. `CallWixSiteAPI`).
+2. Use the discovered tool name and retry the call.
+3. **Do NOT bail.** Only escalate to the user if discovery itself returns no match.
+
+This guards against parents that forgot to pass the prefix and against future prefix-scheme changes.
+
+---
+
+## Prefer bundled reference docs over external doc reads
+
+Your agent directory includes `.md` reference files with API recipes, call templates, and error handling tailored to your scope. These are your primary source — they document the exact call patterns, body shapes, and edge cases for your use case.
+
+The Wix MCP also exposes documentation tools (`SearchWixRESTDocumentation`, `ReadFullDocsArticle`, `SearchWixSDKDocumentation`, etc.). These are useful when you hit an error or edge case not covered by your reference files. But **prefer your bundled `.md` files first** — each external doc read costs a tool call and 15-30s, and the bundled recipes are already validated for this plugin's flows.
+
+**Rule of thumb:** read your reference files → try the documented recipe → only if you get an unexpected error or need an endpoint not covered, fall back to the MCP doc tools.
+
+---
+
+## Absolute paths — never trust CWD-relative instruction locations
+
+Subagents launched by the orchestrator run with the project directory as CWD (e.g. `/Users/.../headless-projects/chairloom/`), not the skill root. Your instruction file and its sibling references live **inside the skill**, not in your CWD — e.g. the stores instructions live at `<skill-root>/references/stores/INSTRUCTIONS.md`.
+
+**Rule:** every implementer prompt MUST include an `Instruction file (absolute path)` line pointing at the right `INSTRUCTIONS.md`. Read that file and only that path. Then use the absolute paths it lists for sibling references. Never:
+
+- Resolve `references/stores/INSTRUCTIONS.md` against your CWD — it doesn't exist there.
+- `Glob **/INSTRUCTIONS.md` or `**/agents/**` to "find" your instructions — that walks the project tree and finds nothing relevant; it's the most expensive failure mode in current runs.
+- Walk up from the project directory looking for the skill root — guess wrong and you'll burn minutes globbing.
+
+If your prompt is missing the absolute `Instruction file` line, ask the parent (don't guess). The `wix-headless` skill is responsible for computing and passing this absolute path in every agent-launch prompt (see `references/ORCHESTRATION.md` § "Agent prompt template").

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

@@ -0,0 +1,97 @@
+# Production Sharp Edges
+
+Use this reference when a Wix Headless run touches production release, SEO-controlled root files, favicon behavior, or multi-site orchestration.
+
+## Release Retries
+
+`wix release` can hit transient backend/network errors after upload or during publish. Known retryable signals include:
+
+- `ECONNRESET`
+- `ETIMEDOUT`
+- `EAI_AGAIN`
+- `STATE_MISMATCH`
+- `temporary system error`
+- `try again shortly`
+
+The bundled `scripts/release.sh` retries these known transient release failures. Do not retry build failures; TypeScript, Astro, missing import, and missing module failures are code issues that must be fixed before another release attempt.
+
+For batch releases across many projects, prefer releasing failed sites one by one after the current deployment state settles. Parallel release is useful for throughput, but retry serially when Wix reports state-machine errors.
+
+## Reserved Root Paths
+
+Wix can intercept root paths before the Astro app serves them. Do not assume files in `public/` or root Astro routes will win for these URLs:
+
+- `/robots.txt`
+- `/llms.txt`
+- `/favicon.svg`
+
+### `robots.txt`
+
+Use the Wix SEO robots REST endpoint instead of `public/robots.txt`:
+
+```http
+PUT https://www.wixapis.com/promote-seo-robots-server/v2/robots
+```
+
+```json
+{
+  "robotsTxt": {
+    "content": "...",
+    "default": false,
+    "subdomain": "www"
+  }
+}
+```
+
+`default: true` resets to Wix's built-in robots file.
+
+### `llms.txt`
+
+Use the sibling Wix SEO endpoint instead of `public/llms.txt` or `src/pages/llms.txt.ts`:
+
+```http
+PUT https://www.wixapis.com/promote-seo-robots-server/v2/llms
+```
+
+```json
+{
+  "llmsTxt": {
+    "content": "...",
+    "default": false,
+    "subdomain": "www"
+  }
+}
+```
+
+Do not use `default: true` for custom `llms.txt`; in observed runs it caused `/llms.txt` to return `404`.
+
+Wix may mutate `llms.txt` content by:
+
+- prepending an H1 from the site/business title
+- wrapping the first submitted line as a tagline blockquote
+- appending AI Agent Access and available MCP tools sections
+
+Start custom content with the intended tagline, not another H1.
+
+### Favicon
+
+Wix may intercept `/favicon.svg`, even if the project has `public/favicon.svg` or `src/pages/favicon.svg.ts`.
+
+When a run needs a custom favicon and no site-favicon API/CLI is available, embed the SVG directly in the document head:
+
+```html
+<link rel="icon" type="image/svg+xml" href="data:image/svg+xml;base64,..." />
+```
+
+Keep the source SVG in `public/favicon.svg` for repository readability, but do not use `/favicon.svg` as the browser-facing href unless a live fetch proves Wix is serving the project asset.
+
+## Verification
+
+For production checks, verify the final rendered HTML and edge-controlled files separately:
+
+- For favicon: fetch the live page HTML and confirm the `<link rel="icon">` points to the expected data URI or supported favicon URL.
+- For `robots.txt`: fetch `/robots.txt` after the REST update.
+- For `llms.txt`: fetch `/llms.txt` after the REST update and account for Wix-injected sections.
+- For custom domains: check both the Wix-hosted URL and custom domain when available, because domain propagation and redirects can differ.
+
+Do not construct URLs by editing the release URL from memory. Use the exact release URL printed by the CLI or the configured custom domain.