@wix/agent-skills 1.6.0 → 1.8.0

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

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

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

@@ -0,0 +1,85 @@
+# 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
+spacing:
+  <scale-level>: <Dimension|number>
+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 |
+| `spacing` | `--spacing-<key>` | full `2xs…4xl` rhythm scale |
+| `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 |
+
+### 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

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

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

@@ -1,15 +1,15 @@
 # Recipe: AI Image Generation + Wix Media Import
 
-Generate images using **Wix AI (Runware)** via the Wix MCP, then import them into Wix Media. This is a **pure utility** — it generates an image and returns the result. The calling skill owns prompt construction and entity attachment.
+Generate images using **Wix AI (Runware)** via the `wixapis.com` REST proxy, then import them into Wix Media. This is a **pure utility** — it generates an image and returns the result. The calling skill owns prompt construction and entity attachment.
 
-Image generation is MCP-authenticated — no API keys, no curl, no sandbox escape hatches. Runs automatically whenever the image agent launches.
+Image generation authenticates with the same CLI-minted site-scoped token used for every other Wix REST call in this skill (see `AUTHENTICATION.md`) — no separate API keys, no MCP, no sandbox escape hatches.
 
 ## Step 1: Generate Image via Wix AI
 
-Call the Runware proxy through `CallWixSiteAPI`. The body is an **array of tasks** — one request can generate N images by adding more task objects.
+Call the Runware proxy through `curl`. The body is an **array of tasks** — one request can generate N images by adding more task objects.
 
 ```
-CallWixSiteAPI: POST https://www.wixapis.com/runwareschemaless/v1/request
+REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 body: [
   {
     "taskType": "imageInference",
@@ -25,7 +25,7 @@ body: [
 ]
 ```
 
-Before the first call, ensure the `CallWixSiteAPI` tool schema is loaded (the orchestrator's Step 0 MCP bootstrap covers this — see `<SKILL_ROOT>/references/commands/mcp-bootstrap.md`) so `body` is sent as a real JSON array (not a stringified blob). Use your runtime's tool-discovery primitive if you need to (re-)load it.
+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.
 
@@ -44,7 +44,7 @@ Extract `data[0].imageURL` from the response. This is a short-lived URL — **im
 
 ### 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`:
+Runware enforces a fixed set per model. Start with these:
 
 | Aspect | Size | Use for |
 |--------|------|---------|
@@ -58,14 +58,33 @@ If a 400 response lists supported dimensions, use one from that list — do not
 
 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
+## 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
 
 ```
-<prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request
+REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 body: [
   { "taskType": "imageInference", "taskUUID": "<uuid-1>", "positivePrompt": "...", ... },
   { "taskType": "imageInference", "taskUUID": "<uuid-2>", "positivePrompt": "...", ... },
@@ -76,53 +95,35 @@ One round-trip. Response's `data[]` array contains one result per task, matched
 
 ### For `google:4@2` (the default): N parallel 1-task sibling calls
 
-`google:4@2` times out with `504` when a single request bundles N≥3 tasks — Runware's backend serializes work per request and the model is slow enough that large batches exceed the proxy timeout. Instead, emit **N parallel `CallWixSiteAPI` tool calls as siblings in one concurrent batch**, each carrying one task:
+`google:4@2` times out with `504` when a single request bundles N≥3 tasks — Runware's backend serializes work per request and the model is slow enough that large batches exceed the proxy timeout. Instead, emit **N parallel `curl` tool calls as siblings in one concurrent batch**, each carrying one task:
 
 ```
 Assistant message (single turn, multiple tool calls):
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task1 ]
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task2 ]
-  <prefix>CallWixSiteAPI: POST /runwareschemaless/v1/request  body: [ task3 ]
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
+  REST: POST https://www.wixapis.com/runwareschemaless/v1/request
 ```
 
-All three fire in parallel (runtime dispatches concurrent siblings concurrently). No 504, no sequential wait. The important constraint is *one concurrent batch* — splitting them across turns loses the parallelism and degenerates into the anti-pattern below.
-
-### 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**.
+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
 
-The following procedure prevents the observed serialization anti-pattern. Follow these steps in order:
+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 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.
+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.
 
-**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).
+**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:
 
 ```
-CallWixSiteAPI: POST /site-media/v1/files/import
+REST: POST https://www.wixapis.com/site-media/v1/files/import
 body: {
   "url": "<imageURL from Runware response>",
   "mimeType": "image/png",
@@ -182,4 +183,4 @@ Every prompt should incorporate the full brand context available from the discov
 | Wix Media import fails | Skip this image, entity gets no image |
 | All images fail | Proceed without images, return `status: "failed"` with the root cause |
 
-**Never block the main flow on image generation failure.** Products, posts, and pages work without images — users can upload their own via the Wix dashboard later.
+**Never block the main flow on image generation failure.** Products, posts, and pages work without images — users can upload their own via the Wix dashboard later.

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

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -8,61 +8,54 @@ 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` | — |
+| `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 (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.
+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 `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.
+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.
 
-Standard scope names (see architecture-proposal §3):
-- `seed` — Seed phase (MCP data setup, no frontend code)
+**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`)
 
-## 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.
+## REST auth
 
-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.
+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`.
 
-## Reading `.wix/site.json`
+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.
 
-Every agent reads `.wix/site.json` at the start of its run. The file is the single source of truth for per-project data:
+## Don't depend on mutable shared state (one scoped exception: `.wix/seeded.json`)
 
-```jsonc
-{
-  "brand":        { "name": "...", "description": "..." },
-  "seeded":       { "stores": { "products": [...] }, "cms": { "collections": {...} }, ... },
-  "designTokens": { "colors": {...}, "fonts": {...}, "radii": {...}, "spacing": {...} },
-  "verticals":    ["stores", "ecom", "cms"]
-}
-```
+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 reads:**
+**Phase-specific inputs:**
 
-| Scope | What to read from site.json |
+| Scope | Where its inputs come from |
 |---|---|
-| `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. |
+| `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`/`spacing`/`rounded`/`containers`) 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 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.
+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 write their data for the orchestrator to aggregate
+## 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 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.
+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-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.
+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.
 
@@ -126,30 +119,88 @@ The full styling contract (tokens-as-utilities default, when global semantic cla
 ## 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:
+- **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-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.
+  Without it, the build breaks at release time with `Cannot apply unknown utility class 'gap-sm' …` 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 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`).
+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 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 |
+| 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-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)"` |
+| 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 |