@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -1,84 +0,0 @@
-# DESIGN.md — the design-token format (vendored spec)
-
-`DESIGN.md` is the **single design artifact** of the wix-headless design-system phase. The Designer authors it; `emit-design-tokens.mjs` writes it + projects `.wix/design-tokens.css` and `.wix/site.d.ts` from it; `compose.mjs` reads its **frontmatter** to write the astro design-system files. It is the standalone, framework-agnostic spec a non-astro frontend, a human, or another tool can read.
-
-This file is the **canonical spec inside the skill** — the public DESIGN.md frontmatter format (the `design.md` spec, captured here) plus the small, documented extensions this skill uses. Do not depend on the external `design.md` project at runtime.
-
-## Frontmatter structure
-
-A `DESIGN.md` file is YAML frontmatter delimited by `---`, optionally followed by a free-form markdown body:
-
-```yaml
----
-version: alpha          # optional
-name: <string>          # the brand / design-system name
-colors:
-  <token-name>: <Color>
-typography:
-  <token-name>:
-    fontFamily: <string>
-    fontSize: <Dimension>        # optional (unused by this skill)
-    fontWeight: <number>         # optional
-    lineHeight: <Dimension|number>  # optional
-    letterSpacing: <Dimension>   # optional
-rounded:                # corner radii (DESIGN.md's name for radius tokens)
-  <scale-level>: <Dimension>
-containers:             # EXTENSION (this skill): content/reading widths
-  <scale-level>: <Dimension>
-googleFontsHref: <string>   # EXTENSION (this skill): the ready Google Fonts <link> href
----
-
-# free-form body — documentation only, NEVER parsed
-```
-
-### Value types
-
-- **Color** — any valid CSS color string (hex `#RRGGBB`, `rgb()`, `hsl()`, named). **Quote hex values** — an unquoted `#hex` after `: ` is a YAML comment.
-- **Dimension** — a string with a unit suffix: `px`, `em`, `rem` (e.g. `"1rem"`, `16px`).
-- **Token reference** — `{path.to.value}` (curly-brace object path into the YAML tree).
-
-## How this skill uses it
-
-### Frontmatter only is canonical
-
-`compose.mjs` and `emit-design-tokens.mjs` read the **frontmatter only**. The markdown body is documentation and is **never parsed** — so a generated `DESIGN.md` can carry a minimal or empty body without affecting the build, and run-to-run body variance never reaches the output.
-
-### Token vocabulary (the groups this skill consumes)
-
-| DESIGN.md group | wix CSS projection | Notes |
-|---|---|---|
-| `colors` | `--color-<key>` | semantic role keys (see color roles below) |
-| `typography.<level>.fontFamily` | `--font-<level>` | `display` + `body` required; `mono` optional |
-| `rounded` | `--radius-<key>` | `sm` + `md` required |
-| `containers` | `--container-<key>` | **extension** — content widths, a separate axis from spacing (`prose, md, 3xl, 6xl`) |
-| `googleFontsHref` | the Layout `<link>` href | **extension** — the ready stylesheet URL for the chosen families |
-
-> **Spacing is not a DESIGN.md token.** The build uses Tailwind v4's built-in numeric spacing scale directly (`gap-4`, `py-24`, `px-6`, …). A named `--spacing-<size>` scale was removed because its t-shirt names (`md`, `3xl`, …) collided with the width utilities (`max-w-3xl` resolved to `--spacing-3xl` instead of `--container-3xl`). Do not author a `spacing` group.
-
-### Color roles — wix-native keys are the contract
-
-The skill's component-CSS templates reference a fixed set of `--color-*` names (`STYLING.md` § "Required tokens"). So the **canonical color token keys in our DESIGN.md are the wix editorial roles** — and these are valid DESIGN.md color token names (the format leaves token names free-form):
-
-`paper` (primary background), `paper-warm` (secondary surface), `ink` (primary text / dark fills), `ink-soft`, `mute` (muted text), `rule` (borders / dividers), `accent` (brand emphasis), `cream`, `error`.
-
-`paper`, `paper-warm`, `ink`, `mute`, `rule`, `accent` are **required**; `ink-soft`, `cream`, `error` recommended (derived as a fail-safe if absent).
-
-### Standard-role compatibility (reading an externally-authored DESIGN.md)
-
-A DESIGN.md authored elsewhere may use the DESIGN.md spec's *common* semantic roles instead of the wix-native keys. `compose.mjs` carries a **role-translation table** so such a file is still consumable; wix-native keys are not in the table and pass through unchanged (winning on conflict):
-
-| standard role | → wix `--color-*` | | standard role | → wix `--color-*` |
-|---|---|---|---|---|
-| `primary` | `accent` | | `surface` / `background` | `paper` |
-| `secondary` | `paper-warm` | | `on-surface` / `on-background` | `ink` |
-| `tertiary` | `ink-soft` | | `outline` | `rule` |
-| `neutral` | `mute` | | `error` | `error` |
-
-This translation is a **compatibility layer**, not the authoring path: the Designer in this skill emits the wix-native keys directly (lossless — no role round-trip), so `STYLING.md` and every `components-<pack>.css` template stay untouched.
-
-## Producers & consumers in the run
-
-- **Designer** (`DESIGN_SYSTEM.md`) — **authors `DESIGN.md` directly** (its frontmatter is the spec); returns only the brand-voice strings + the `DESIGN.md` path.
-- **`emit-design-tokens.mjs`** — reads the Designer's `DESIGN.md` and projects `.wix/design-tokens.css` + `.wix/site.d.ts` from its frontmatter. It does **not** write `DESIGN.md` (the Designer does).
-- **`compose.mjs`** — reads `DESIGN.md` frontmatter → writes the 6 astro design-system files (astro only).
-- **Non-astro (`own`) frontends** — import `.wix/design-tokens.css` for the same values; component composition stays framework-native (no `compose.mjs`).

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

@@ -1,41 +0,0 @@
-# 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,186 +0,0 @@
-# Recipe: AI Image Generation + Wix Media Import
-
-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 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 `curl`. The body is an **array of tasks** — one request can generate N images by adding more task objects.
-
-```
-REST: 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
-  }
-]
-```
-
-Send `body` as a real JSON array (not a stringified blob). Auth uses the CLI-minted site-scoped token and the standard headers — see `<SKILL_ROOT>/references/shared/AUTHENTICATION.md`.
-
-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:
-
-| 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`.
-
-## Preferred: run the whole phase through `generate-images.mjs`
-
-Generation + Wix Media import is **embarrassingly parallel** (N independent `generate → import` chains, no cross-image dependency) and **recipe-free** (no entity write-shapes), so it is best run by a deterministic script rather than by hand. `<SKILL_ROOT>/scripts/generate-images.mjs` does exactly this: it fires every image as a **concurrent single-task request in one process** (`Promise.all`), then imports each result to Wix Media — all in parallel — and returns a `key → {url, fileId}` map. Because each task is its **own** request (not N tasks in one body), it sidesteps the `google:4@2` N≥3-in-one-request 504 entirely, and because the parallelism lives in code it cannot degrade into the sequential-turns anti-pattern below.
-
-```bash
-echo '{
-  "siteId": "<siteId>",
-  "model": "google:4@2",
-  "images": [
-    {"key": "hero",  "positivePrompt": "<prompt>", "width": 1376, "height": 768},
-    {"key": "about", "positivePrompt": "<prompt>", "width": 1200, "height": 896}
-  ]
-}' | WIX_TOKEN="$TOKEN" node <SKILL_ROOT>/scripts/generate-images.mjs
-```
-
-`key` is a **slot name** for Phase 1 (`hero`, `about`) or an **entityId** for Phase 2. The returned `slots` map (key→url) pipes straight into `write-decorative-json.mjs` (Phase 1); the `map` (key→{url,fileId}) feeds the entity PATCH/PUT/publish recipe (Phase 2). Pass the **already-minted** site token via `WIX_TOKEN` (mint-once — `AUTHENTICATION.md`); the script mints its own only as a fallback. Per-image failures are isolated (`status: "partial"`), and `x-wix-request-id` is captured per call into `results[]` for trace analysis.
-
-The manual `curl` shapes below remain the **reference for the request bodies** the script builds, and the **fallback** when the script can't be used. The "one concurrent batch" rule still applies if you ever hand-drive a phase.
-
-## Required (manual fallback): 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
-
-```
-REST: POST https://www.wixapis.com/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 `curl` tool calls as siblings in one concurrent batch**, each carrying one task:
-
-```
-Assistant message (single turn, multiple tool calls):
-  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: sequential 1-task calls across multiple turns each add inter-message overhead.
-
-### Procedure to enforce batching
-
-Whether you batch one request or fire parallel siblings, **all calls in each stage MUST be in one concurrent batch**. 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 generation call(s).** For `bfl:5@1` / `runware:400@1`, one batched call with the full body array; for `google:4@2`, N parallel 1-task sibling calls. Verify the task count matches the entity count.
-3. **Generate.** Fire that generation as one concurrent batch.
-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. See the skill's `references/PLAN.md` § "Batching discipline" for why sibling batching beats sequential dispatch.
-
-## Step 2: Import to Wix Media
-
-This API is Wix-side and model-agnostic — the same shape works for any image source:
-
-```
-REST: POST https://www.wixapis.com/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

@@ -1,206 +0,0 @@
-# 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, bookings). 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`, `DOCS_SEARCH.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(s) (see your vertical's `INSTRUCTIONS.md` scope table). Do NOT read references for scopes **not** named in your prompt — wastes context and blurs ownership.
-
-## Phase routing
-
-Your prompt includes a line naming your scope(s). Map **each** scope to its reference set per your vertical's `INSTRUCTIONS.md` scope table. If the scope line is missing, stop and ask the parent — do not guess.
-
-**Merged dispatch (the common case — one agent owns components + pages for a vertical).** Your prompt may list **several** scopes — e.g. `Scopes (write in this order): components, pages-products, pages-categories`. This is a single "build" agent for one vertical: read the **union** of those scopes' references and write them in the order given — **islands/components FIRST, then the pages/routes that mount them.** Writing the page before its island leaves a dangling import; the within-agent order is exactly why these were merged into one dispatch (it removes the cross-agent Components→Pages barrier). You still own only the files those scopes declare; do not touch another vertical's files or a shared shell unless your scope list explicitly includes a shell-patching `pages` scope.
-
-Standard scope names:
-- `seed` — Seed phase (REST 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`)
-
-## REST auth
-
-Scopes that call Wix APIs (`seed`, image phases) receive `siteId` in the prompt. Mint once: `TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")`. Every `curl` uses the headers in `references/shared/AUTHENTICATION.md`. Doc lookups use the public REST endpoints listed in `references/shared/DOCS_SEARCH.md`.
-
-If your scope is `components` or `pages`, you should NOT make REST calls — those scopes are frontend-only. If you find yourself needing a site API call, it's a scope violation — return `status: "partial"` with an error note, do not proceed.
-
-## Don't depend on mutable shared state (one scoped exception: `.wix/seeded.json`)
-
-Every input you need is either inlined in your prompt or — for seeded entity IDs — in **`.wix/seeded.json`**, the one shared file you are allowed to read. The orchestrator holds run state in scratch, not on disk — it is **not** a coordination channel you can read. `.wix/seeded.json` is the one exception: a producer→consumer handoff written **once** at the seed gate, read-only thereafter. Read **only your own `<vertical>` slice**; never write it.
-
-**Phase-specific inputs:**
-
-| Scope | Where its inputs come from |
-|---|---|
-| `seed` | All **inlined**: `brand`, `intent.<pack>`, `siteId`, recipe path(s). Do NOT re-derive these. |
-| `components` | **Inlined**: `brand`. **Read from disk**: the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`rounded`/`containers`; spacing is Tailwind's numeric scale, not a token) from `.wix/design-tokens.css` (gate-verified present; also the CSS variables the build consumes). Components do not need seeded IDs. |
-| `pages` / `pages-*` | **Inlined:** `brand`. **Read from disk:** the design tokens (`.wix/design-tokens.css`, DESIGN.md vocabulary); your `seeded.<vertical>` slice from `.wix/seeded.json` (products, posts, collections IDs). Page data wiring uses live SDK queries; the `seeded` data is for path resolution + demo content authoring. |
-
-If a required **inlined** input is missing from your prompt, or your **`.wix/seeded.json` slice** is absent (e.g. you are dispatched as `pages-products` but `.wix/seeded.json` has no `seeded.stores`), fail fast — return `status: "failed"` with `errors: [{ code: "SEEDED_JSON_SLICE_MISSING", missing: "seeded.stores.products" }]` (or `PROMPT_INCOMPLETE` for an inlined gap). Do NOT re-fetch via curl — the gap means an upstream phase didn't complete, and re-querying would mask the real bug.
-
-## Seeders return data; orchestrator aggregates → `.wix/seeded.json`
-
-Agents with `Scope: seed` return their seeded entities in the `data` block of the standard return (see `RETURN_CONTRACT.md`). The orchestrator collects every seeder return into its session scratch and writes the aggregated map **once** to `.wix/seeded.json` at the seed gate; per-vertical Page / wiring agents then read their own slice from that file (no inlined slice). (The single Image Phase 2 dispatch keeps its slice inlined.) You do NOT write `.wix/seeded.json` (the orchestrator is its sole writer), and you do NOT write `.wix/seed-returns/<pack>.json` — your JSON return is the contract.
-
-## Writing page files
-
-Pages-phase agents write route files (`.astro`) with:
-
-1. **Visual design via design tokens and Tailwind.** Reference tokens as `var(--color-accent)` in `<style>` blocks or `bg-[--color-accent]` 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 entity IDs / slugs from your `seeded.<vertical>` slice in `.wix/seeded.json` (with the `Read` tool — not by `import`). Pages query the Wix SDK at request time (`await productsV3.queryProducts(...)`) — that's the production-correct pattern. Use the `seeded` data for path generation (e.g. `getStaticPaths` slugs) and for authoring demo content where needed; do NOT `import` `.wix/seeded.json` from page files — it sits outside the bundler root and reading it at author-time (not bundling it) keeps it out of `dist/`.
-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-accent)" }}` is fine.
-- **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. If your scope writes a `components-<vertical>.css` that uses `@apply` with theme tokens (e.g., `@apply gap-3 font-display text-sm`), the file MUST start with:
-  ```css
-  @reference "./global.css";
-  ```
-  Without it, the build breaks at release time with `Cannot apply unknown utility class 'gap-3' …` 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 REST 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 universal envelope: skeleton, status semantics, no-trailing-prose rule). 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`).
-
-The `data` shapes for the scopes this file owns — `components` and `pages`/`pages-*` — are below. (Seed `data` shapes live in your per-vertical `INSTRUCTIONS.md` § Seed return.)
-
-**`components` scope** (`phase: "<pack>-components"`):
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote React islands + utils; wired analytics; contract classes referenced: 7",
-  "data": {
-    "islands": ["ProductPurchase.tsx", "CartView.tsx", "AddToCartButton.tsx", "CartBadge.tsx"],
-    "utils": ["wix-image.ts", "analytics.ts"],
-    "astroComponents": ["SeoTags.astro"]
-  },
-  "files": [
-    "src/utils/wix-image.ts",
-    "src/utils/analytics.ts",
-    "src/components/SeoTags.astro",
-    "src/components/AddToCartButton.tsx",
-    "src/components/CartBadge.tsx",
-    "src/components/ProductPurchase.tsx",
-    "src/components/CartView.tsx"
-  ]
-}
-```
-
-**`pages` / `pages-*` scope** (`phase: "<pack>-pages[-<group>]"`):
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages-products",
-  "scope": "pages-products",
-  "data": {
-    "pagesWired": 2,
-    "wixMetadataExported": true,
-    "seoTagsMounted": true,
-    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/components/ProductCard.astro"
-  ]
-}
-```
-
-## Common failure modes
-
-| Wrong | Right |
-|---|---|
-| Reading references for scopes **not** listed in your prompt | Read only the references for your declared scope(s) — the union when it's a merged build dispatch |
-| Writing a page/route before the island it mounts (merged dispatch) | Write islands/components FIRST, then the pages — in the prompt's scope order |
-| Issuing REST calls from a `components` or `pages` scope | Components/Pages are frontend-only; read `seeded` data from your `.wix/seeded.json` slice (pages only) — never curl |
-| Re-querying when your `seeded.<vertical>` slice is missing from `.wix/seeded.json` | Fail fast with `SEEDED_JSON_SLICE_MISSING` — an upstream phase didn't complete (do NOT re-query) |
-| Depending on mutable shared state the orchestrator holds in scratch | Every input is inlined; the one shared file you may read is your `.wix/seeded.json` slice (read-only) |
-| Inventing class names for layout/spacing/typography (`.productCard`, `.heroSection`) | Tailwind utilities derived from `@theme` tokens (`class="flex flex-col gap-4"`, `class="py-24"`). 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-accent)"` |
-| Creating a new cross-cutting class name | Extract a shared primitive component instead |
-
-### Astro/React build-blockers — check before returning `complete`
-
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| HTML-style comments in `.astro` frontmatter | `grep '<!--' *.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript. Surfaces at build as `Legacy HTML single-line comments`. |
-| Missing `wixMetadata` on `/products/[slug]` | Check exports | Add the metadata export — required for Wix platform indexing |
-| `import { products }` instead of `productsV3` | `grep 'from "@wix/stores"'` import line | V1 silently returns 0 on V3 catalogs |
-| Missing `variantId` in cart operations | Check `catalogReference.options` | Always include — single-variant products have one |
-| React island using default Tailwind color class | `grep 'bg-blue-\|bg-green-\|text-red-\|bg-gray-' *.tsx` | Use brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |

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

@@ -1,97 +0,0 @@
-# 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 conductor's release step (the shared release tail, `BUILD.md` § "Shared release tail" — `BUILD-astro.md` § "Build & Release" for astro, `BUILD-own-build.md` § "Release" for no-build frameworks) retries these known transient release failures serially — up to 3× with `attempt * 5`s backoff. 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` — setting `default: true` returns `404` for custom `llms.txt` content.
-
-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.