@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-docs
-description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`) **or by browsing** the docs tree as a menu from the `llms.txt` root (append `.md` to any docs path), then read the page by appending `.md` to its URL; and (2) the Wix MCP doc tools when your agent has them. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
+description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`) **or by browsing** the docs tree as a menu — a structured, typed, counted browse of the REST API reference (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any portal — then read the page by appending `.md` to its URL; and (2) the Wix MCP doc tools when your agent has them. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
 ---
 
 # Wix Docs — look up the Wix API/SDK documentation
@@ -54,8 +54,40 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
 # no jq? → python3 -c 'import sys,json;[print(r["title"],r["url"]) for r in json.load(sys.stdin)["results"] if r.get("url")]'
 ```
 
-**B. Browse the tree from the root, like a menu.** Every docs path has a `.md` twin, so you can
-navigate the docs as a menu tree — no search needed. `curl https://dev.wix.com/docs/llms.txt` is the
+**B. Browse the docs tree as a menu.** Two ways: the **structured browse endpoint** for the REST
+API reference (preferred there — typed, counted, filterable), and the **`.md` menu tree** for every
+portal and for reading pages.
+
+**B1. Structured browse — REST API reference (`api-reference`).** `POST
+/mcp-docs-search/v1/docs/menu/browse` walks the tree and returns each child with its **kind**, its
+**HTTP verb** (for methods), and **subtree counts** ("Catalog V3 — 121 methods, 32 articles"), so
+you pick the right area by shape — in ~2 KB, not a ~40 KB menu page you have to `grep`. `include`,
+`name_filter`, and `depth` jump straight to what you want. Body: `menu_url?` (absolute docs URL;
+omit for the portal root — the top-level verticals), `document_type?` (`REST`, default), `depth?`
+(1, max 6), `include?` (`CATEGORY`·`RESOURCE`·`METHOD`·`ARTICLE`·`WEBHOOK`·`OBJECT`·`SKILL`),
+`deprecated?` (`HIDE` default·`SHOW`·`ONLY`), `name_filter?`, `format?` (`MARKDOWN` default →
+`content` string; `STRUCTURED` → JSON tree with `url`/`http_method`/`resource_id`/`child_counts`).
+
+```bash
+# a vertical's structure, with per-child subtree counts
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/stores"}' \
+  | jq -r '.content'
+
+# jump straight to a method by name — no multi-level grep
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/bookings","include":["METHOD"],"name_filter":"cancel","depth":4}' \
+  | jq -r '.content'
+```
+
+REST (`api-reference`) only, and browse-only: it hands you the page **URL** — read it by appending
+`.md` (§2), and get the exact schema from §C.
+
+**B2. `.md` menu tree — every portal, and how you read pages.** Every docs path has a `.md` twin, so
+you can navigate any portal with zero dependencies; use it for the **non-REST portals** (SDK, Velo,
+Headless, CLI) and to read leaves. `curl https://dev.wix.com/docs/llms.txt` is the
 top-level map; the portals under it:
 
 | Portal | Start here for |

package/skills/wix-headless/SKILL.md

@@ -117,11 +117,13 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | What | Path |
 |---|---|
 | Vertical index (intent matching + per-vertical site spec) | `<SKILL_ROOT>/references/CAPABILITIES.md` |
-| Discovery (infer capabilities + brand + intent) | `<SKILL_ROOT>/references/DISCOVERY.md` |
+| Discovery (infer capabilities + brand + intent; existing site → the Dynamic Context call in §1) | `<SKILL_ROOT>/references/DISCOVERY.md` |
 | Setup (install apps) | `<SKILL_ROOT>/references/SETUP.md` |
 | Seed (create backend content) | `<SKILL_ROOT>/references/SEED.md` |
 | SDK-integration handoff (emitted, or applied by create/connect) | `<SKILL_ROOT>/references/SDK_HANDOFF.md` |
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
+| Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
+| Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |

package/skills/wix-headless/references/CONTENT.md

@@ -0,0 +1,36 @@
+# Content — default copy quality bar for the built frontend (managed create)
+
+**Applies when this skill writes frontend page copy from scratch** (managed `create`, `CREATE.md` §4) — hero/section headlines, subtitles, kickers, CTA labels, and any image captions the pages include. Same scope as `DESIGN.md`: not `connect`/`iterate` (the copy already exists there).
+
+**Same precedence rule as `DESIGN.md`: fallback, not override.** If the user supplied their own copy, brand voice, or tone direction, use theirs — don't overwrite it to match the conventions below. The one exception is **§1** — a comprehension floor, not a style preference: whatever the voice, a first-time visitor must still be able to tell what the business *is* from the hero.
+
+## 1 · Say what the business is — explicitly, above the fold
+
+- A first-time visitor must know what the site *is* and what they can *do*, straight from the hero — never left to infer from mood or voice alone.
+- The **business category** (e.g. "yoga studio", "restaurant", "construction services") must appear **literally** in at least one of: the H1, a kicker above the H1, or the **first clause of the subtitle**. A witty H1 alone is not enough.
+- The **subtitle leads with the offer**, in plain language, before any flavor — put the verb the visitor actually cares about early ("Book…", "Order…", "Learn…", "Hire…").
+- Voice-driven, evocative H1s are welcome — but only when the category sits explicitly right beside them (kicker or subtitle). When in doubt, name the category in the kicker.
+
+## 2 · Kickers (micro-copy above titles)
+
+- **Cut a kicker that only restates the title** (e.g. "The Courses" above a Courses heading) — it adds nothing.
+- **Keep a kicker that carries real information**: category + location ("Yoga Studio · Downtown"), a feature's proper name, event details, dates, price framing.
+- A kicker is the right place to satisfy §1 when the H1 itself is voice-led rather than literal.
+
+## 3 · Titles, subtitles, paragraphs, CTAs
+
+- **Titles and subtitles end without a period.** Paragraphs (full running sentences) keep theirs.
+- No fluff — every line should move the visitor's understanding forward, the H1 and subtitle most of all.
+- **CTA labels are short and avoid all-caps** unless a specific reason demands it (readability). Word them to the actual action (ties to `DESIGN.md` §2's "one primary CTA, worded to the action" rule) — not generic verbs.
+
+## 4 · Images — the real subject comes first
+
+- **At least one image on the page must show the real story of the business** — the actual thing, not just abstract graphics, dashboards, or decorative art. A climbing outfitter shows mountains and climbers; a clinic shows the room; a workshop shows the tools and hands at work.
+- **Decorative/supporting visuals (illustrations, icons, patterns, textures) layer in *addition to* the real subject, never *instead of* it.** They earn their place by reinforcing the story and mood once the business is genuinely shown — not by standing in for it.
+- Imagery (real or decorative) matches the tone, voice, and era of the business.
+- When the user must supply their own real photos (the business has a specific, particular space/product/person that generated imagery can't stand in for), use a **fillable image slot with a descriptive placeholder** naming exactly what belongs there — not a generic stock image presented as final.
+
+## 5 · Image captions
+
+- A caption describes what is **actually seen** in its image. Tone can vary (serious, playful, informative) but must stay aligned with the image's real content.
+- **No meaningless captions, and no caption that ignores the image.** A slogan or pull-quote overlaid on a photo is not a caption — if a true caption is wanted, write one that describes the scene once the real image is in place.

package/skills/wix-headless/references/DESIGN.md

@@ -0,0 +1,54 @@
+# Design — default visual quality bar for the built frontend (managed create)
+
+**Applies when this skill builds the frontend from scratch** (managed `create`, `CREATE.md` §4). It does **not** apply to `connect`/`iterate` — there the design already exists (brought in by the user), and the job is wiring, not designing (`CONNECT.md` §4).
+
+**This is a fallback, not an override.** It fills the gap **only when the user gave no design direction of their own** — no palette, no "make it dark/minimal/playful," no reference site or screenshot, no brand guidelines. The moment the user specifies *any* of that, their explicit intent wins outright — don't apply a rule below just because it's here if it contradicts what they asked for. Two exceptions that hold regardless of what's requested: **§3 (accessibility)** is a hard floor — if a user-requested palette fails contrast, fix the specific pair to comply, don't ship a violation — and the **anti-genericism intent** of §1 (derive tokens from *this* brand, don't reuse the last project's look) still applies even when the user supplied their own palette/theme, since it's about not being lazy with *their* inputs, not about overriding them.
+
+This is the **agent's own design-tokens contract** — it's the thing `IMAGE_GENERATION.md` and `DISCOVERY.md` §4 already assume exists when they say a themed-block fallback "follows the site's own design tokens (palette, radius, spacing)". Decide the tokens below *before* writing the first component; every page and fallback then draws from that one decision instead of improvising per-component.
+
+## 1 · Decide the design tokens once, before any component
+
+A short, explicit decision — a few lines, not a document — derived from `brand.description`/`brand.vibe` (`DISCOVERY.md` §2):
+
+- **Theme polarity** — light, dark, or vivid/tinted. Argue it from the business, never default to dark for "premium" (a light, high-key theme can be just as strong — e.g. healthcare/wellness usually reads better light).
+- **Palette** — 2–4 hex colors, one dominant + accents drawn from **analogous hues** (adjacent on the color wheel, ~30° arc) — not complementary jumps. Functional colors (error/success/warning) sit outside this count.
+- **Type scale** — one heading scale + one body size. Body text floor: **16px, 1.5 line-height** (§3 is non-negotiable, this is where you set it).
+- **Radius + spacing** — pick once (e.g. "12px radius, 24px section padding") and reuse everywhere; don't let each component invent its own.
+
+Hold these as the run's design tokens. Reuse them literally in the themed-block fallback (`IMAGE_GENERATION.md`) and every page — don't re-derive per page.
+
+**Vary this across projects.** Don't reach for the same palette/theme/layout on every build — derive it from *this* brand's vibe each time. Repeating the same look across unrelated projects is a failure mode, not a shortcut.
+
+## 2 · Layout (hard rules)
+
+- **Full-bleed, not boxed.** Don't wrap the page in a narrow centered container (no `max-w-4xl mx-auto` outer shell). Design for the full viewport; use the peripheral space intentionally.
+- **One primary CTA per page**, worded to the page's actual action — `Book a Table`, `Add to Cart`, `Reserve Your Spot`, not generic verbs ("Submit", "Click here", "Go").
+- **Icons never sit on a filled/tinted background shell** — no circle/square/pill behind a nav or card icon. The glyph renders directly on the surface.
+- **Identify the site's 3–4 core pages/sections from its resolved vertical** (`verticals[]`, `DISCOVERY.md` §1) before laying out anything, and design each to its own intent:
+
+  | Vertical | Core pages/sections to get right |
+  |---|---|
+  | stores | Home hero, product grid, product detail, cart |
+  | blog | Post list, post detail |
+  | cms | Collection list, item detail |
+  | forms | The form itself — clear single-column, one obvious submit |
+  | events | Event list, event detail + RSVP |
+  | bookings | Service list, booking widget/flow |
+  | pricing-plans | Plan comparison, checkout/signup |
+  | restaurants | Menu, reservation/ordering flow |
+  | portfolio | Project grid, case-study/project detail |
+
+## 3 · Accessibility (hard rules, no exceptions)
+
+- **WCAG 2.2 AA contrast** — every chosen background/foreground pair must hit **4.5:1** for body text, **3:1** for large text (≥24px or ≥19px bold). Check the actual hex pair against the ratio — don't assume a palette is accessible because it "looks fine."
+- **16px minimum body font**, **1.5 minimum line-height** for body copy.
+
+## 4 · Content & imagery hygiene
+
+- **No emojis** in UI copy, headings, or empty states.
+- **No stock-photo clichés** — generic handshake/lightbulb/laptop-on-desk imagery reads as filler, not a real page.
+- Generated imagery already carries its own purity rule (no text/logos/watermarks/UI-mockups — `IMAGE_GENERATION.md` § Prompts, "no text, no watermarks"); nothing additional to do here beyond following that section as written.
+
+## What this doesn't cover
+
+This is a floor, not a template library — it constrains the *how* (contrast, layout shape, token discipline), not the *what* (that's `verticals[]` + `brand` from Discovery, and the user's intent). Two builds with the same vertical and different brand vibes should still look nothing alike.

package/skills/wix-headless/references/DISCOVERY.md

@@ -6,6 +6,30 @@ Discovery is pure inference — it needs **no authentication** and is **agnostic
 
 ## 1 · Resolve the capability set
 
+> **Targeting an existing site with an ambiguous brief? Read the site — don't guess.** When the
+> run points at a site that already exists (connect/iterate, a funnel-created site) and an
+> elevated credential is already available, one documented call returns the site's context —
+> installed apps by name (including the Stores catalog version), status, URL,
+> locale/currency/timezone, and CMS collections — as an agent-ready markdown report:
+>
+> ```bash
+> curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+>   -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+>   -d "{\"siteId\": \"$SITE_ID\"}"
+> ```
+>
+> Docs: <https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown.md>
+> (a JSON variant lives at the same path without `/markdown`). With an API key, send it raw as
+> the `Authorization` header value, no `Bearer` prefix.
+>
+> The installed business apps map to the vertical set and seed `verticals[]` directly (CMS
+> collections present → cms); inference below then only fills what the site can't answer
+> (brand, per-capability intent). Several verticals installed → prioritize by the user's words
+> and by which holds real (non-sample) content. Nothing relevant installed → **ask the user one
+> short question** ("what do you offer — products, appointments, posts, events?") rather than
+> defaulting to a store. This is the one case where Discovery may use the authentication
+> mechanism early; with no credential at hand yet, skip it and infer from the words as below.
+
 Read the **user intent** (+ optional project signals: `package.json` name, README, visible copy) against the vertical index in `references/CAPABILITIES.md` — each entry there carries the intent signals that point to it. Pick every vertical that genuinely fits → `verticals[]`. Multiple signals → multiple capabilities. On ambiguity, prefer the more specific vertical; if nothing dynamic is named, fall to the **forms** floor (a contact form). **Never return an empty set.**
 
 Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · pricing-plans · restaurants · portfolio** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.

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

@@ -36,6 +36,14 @@ body: { "url": "<imageURL from generate>", "mimeType": "image/png", "displayName
 
 Keep two values from the `file` object: **`file.url`** (the full permanent `wixstatic.com` URL) and **`file.id`** (the WixMedia file id, e.g. `<hash>~mv2.jpg`). Some entities bind by url, others by id — **which one a given entity uses is the recipe's concern** (§3), not this common section's. (The import response has **no `fileUrl` field** — the id is `file.id`.)
 
+**Importing several images? Use one bulk call, not N singles** — `POST https://www.wixapis.com/site-media/v1/bulk/files/import-v2` (≤100 per call):
+
+```
+body: { "importFileRequests": [ { "url": "<imageURL>", "mimeType": "image/png", "displayName": "<name>.png" }, … ] }
+```
+
+Response is `{ "results": [ { "itemMetadata": { "originalIndex", "success" }, "item": { "url", "id", … } } ] }` — read each hit's **`item.url`** / **`item.id`** (same values as the single import's `file.url` / `file.id`) and its `itemMetadata.success`.
+
 ## 3 · Attach (by entity type)
 
 The pass-2 **write shape is per-entity earned knowledge and lives in each capability's seed recipe** — right next to the create shape the seeder already reads (`inline-recipes/setup-<capability>.md`). **That recipe is authoritative** — read the exact shape there (field paths, any required companion fields, silent-drop warnings, confirm-by-requery), not here. This section is navigation only and carries no shapes:
@@ -57,6 +65,8 @@ The pass-2 **write shape is per-entity earned knowledge and lives in each capabi
 
 Brand-contextual, never generic. Include: subject; the brand aesthetic/mood; the palette (real tones, e.g. "warm cream and forest green"); style/lighting; and always **"no text, no watermarks"** (AI-rendered text is garbled). Pull context from the brand + the entity (product name/description, post topic, page purpose).
 
+**At least one image per page must show the real subject of the business** — the actual service/product/space, not just abstract or decorative art; decorative visuals layer in *addition* to that, never *instead of* it (`CONTENT.md` § Images has the full rule + the fillable-slot fallback for when only the user's own real photos will do).
+
 ## Credits, cost & the not-generating fallback
 
 Each generated image costs **1 Wix AI credit**, billed at the account level regardless of project type (the account behind the metasite must have credits). Volume is bounded in `DISCOVERY.md` §4 — carry those two values through:

package/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md

@@ -52,7 +52,8 @@ A concise contract for writing the **frontend code** of a storefront against a C
 The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
 
 ```jsonc
-// productsV3.queryProducts() / .searchProducts()  →  result.items[]
+// productsV3.queryProducts().…find()  →  result.items[]
+// productsV3.searchProducts({...})    →  result.products[]
 product = {
   _id,                                            // links · cart catalogItemId · variant filter   (NOT .id → empty → HTTP 500)
   slug, name, visible,                            // only visible:true is returned to a visitor token
@@ -119,7 +120,7 @@ const res = await categories.queryCategories({
 **⚠️ CRITICAL: category filtering MUST use `searchProducts`, NOT `queryProducts`.** `directCategoriesInfo.categories` is **not declared as filterable in `queryProducts`** — passing it there returns HTTP `400 "... is not declared as filterable"`, which the SDK **swallows silently**, leaving an empty category page that looks like "no products". This is the #1 way this breaks. Use Search Products:
 
 ```js
-const { items } = await productsV3.searchProducts({
+const { products } = await productsV3.searchProducts({
   filter: { 'directCategoriesInfo.categories': { $matchItems: [{ id: categoryId }] } },
 });
 ```

package/skills/wix-headless/references/inline-recipes/setup-online-store.md

@@ -158,29 +158,38 @@ The request body is `items` (each with the product's `catalogItemId` and the Sto
 
 ### Attach images (imagery ON only — skip otherwise)
 
-**Only when `imagery` is on** (`SEED.md` § "Entity images"). Products were created text-only above; this pass-2 step writes a generated brand image onto each. Generate + import per `references/IMAGE_GENERATION.md`, keep `file.url`, then PATCH the product.
-
-**The exact working call — do this per product (getting it right first time avoids a multi-round debug loop):**
-
-1. **`GET https://www.wixapis.com/stores/v3/products/{id}`** → read `revision`, `options`, and `variantsInfo` from **`response.product.*`**. The product is **nested under a `product` key** — the GET response is *not* flat.
-2. **`PATCH https://www.wixapis.com/stores/v3/products/{id}`** with the body below. **⚠️ Everything nests under a `product` wrapper.** Putting `id` / `revision` / `media` at the **root** fails `400 "product is invalid: revision must not be empty"` — the #1 cause of the loop here. **Do not send a field mask** (the validator runs before masking → `428`):
-
-   ```json
-   {
-     "product": {
-       "id": "<product id>",
-       "revision": "<revision from the GET — required; omitting it is the 400 above>",
-       "media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/…>", "altText": "…" } ] } },
-       "options":      "<echo the GET's product.options, unchanged>",
-       "variantsInfo": "<echo the GET's product.variantsInfo, unchanged>"
-     }
-   }
-   ```
-   The image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`) — either works.
-
-- The field that persists is **`media.itemsInfo.items`**, NOT `media.main`. **⚠️ `media.main` set ALONE silently no-ops** — a `200` comes back but re-query shows no image; that is the trap. The server promotes the first `itemsInfo.items` entry to `media.main` for you, so **verify success by reading `media.main.image.url`** — it must resolve to a `static.wixstatic.com` URL. Check that nested string, **not** the presence of `media.main` (which can be a non-null object with no image and makes a failed attach look successful). Conversely `media.itemsInfo` is **write-only** — it comes back `null` on read, so never assert on it.
-- Send **one image per product** (primary); a larger gallery is out of scope for the seed.
-- **Never block on image failure** — skip and leave the product text-only.
+**Only when `imagery` is on** (`SEED.md` § "Entity images"). Products were created text-only above; this pass-2 step writes a generated brand image onto each. Generate + import per `references/IMAGE_GENERATION.md`, keep each image's `url`.
+
+**Attach every product in ONE call** — `POST https://www.wixapis.com/stores/v3/bulk/products/update` (up to 100 products). You already hold each product's `id` **and `revision`** from STEP 2's bulk-create response (`productResults.results[].item`), so **no per-product `GET` is needed**. Each entry nests under a `product` wrapper carrying just `id`, `revision`, and `media` — options, variants, and every other field are left untouched (it's a partial update):
+
+```json
+{
+  "products": [
+    { "product": {
+        "id": "<product id>",
+        "revision": "<from the create response>",
+        "media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/… or Wix Media id>", "altText": "…" } ] } }
+    } }
+  ]
+}
+```
+
+- **`revision` is required on every entry** — omitting it fails `400 "revision must not be empty"`. Use the revision from the create response (or a fresh query); a stale one fails the optimistic-concurrency check.
+- **Everything nests under `product`** — `id` / `revision` / `media` at the entry root fails validation. **Send no field mask** (the validator runs before masking → `428`).
+- **Write the image via `media.itemsInfo.items`**; the server derives `media.main` from it. One primary image per product (a larger gallery is out of scope for the seed). The image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`) — either works.
+- **Success shape** — `bulkActionMetadata` totals the run, and each result carries an `itemMetadata`:
+
+  ```jsonc
+  {
+    "results": [ { "itemMetadata": { "id": "<product id>", "originalIndex": 0, "success": true } } ],
+    "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0, "undetailedFailures": 0 }
+  }
+  ```
+  Read `itemMetadata.success` per product (the result carries no product body). **Retry only the failed ids once**, then move on.
+- **Confirm by requery** — `POST …/stores/v3/products/query` with `"fields": ["MEDIA_ITEMS_INFO"]`; the attached image is at `media.main.image.url`. Wix **re-hosts** the image on attach, so that URL is a **new** `wixstatic.com` id — verify it's *a* wixstatic URL, never string-equality against the one you sent. The read-back can lag a beat; one empty read right after success isn't a failure.
+- **Never block on image failure** — a product that won't attach stays text-only.
+
+**One-off fix (single product).** To (re)attach a single image later, `PATCH https://www.wixapis.com/stores/v3/products/{id}` with the same `{ "product": { "id", "revision", "media": {…} } }` body — same rules apply (revision required, no field mask, media-only is a partial update that leaves options/variants intact). Read the current `revision` from `GET …/products/{id}` → `response.product.revision` (the GET is not flat); the `200` response carries the image at `media.main.url`.
 
 ---
 

package/skills/wix-headless/references/managed/CONNECT.md

@@ -14,7 +14,7 @@ Run these in order:
 
 **If a `wix.config.json` (or `.wix/`) is already present, the project is already connected to Wix — this is the *iterate* case.** Do **not** run `init` again (it's for attaching a *new* Wix project). Read `./wix.config.json` → hold `SITE_ID` in scratch, and skip to §2.
 
-> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing, check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
+> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing (the Dynamic Context call in `DISCOVERY.md` §1 reports them in one call), check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
 
 Otherwise, attach Wix in place:
 

package/skills/wix-headless/references/managed/CREATE.md

@@ -93,6 +93,20 @@ Run the agnostic flow against the scaffolded site:
   (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`), where `clientId` is the public
   `appId` from the `wix.config.json` written by `init` (§1).
 
+**If the user didn't specify their own design direction** (no palette, no theme/style words, no
+reference site, no brand guidelines), **decide the run's design tokens per `references/DESIGN.md`**
+before writing any component — theme polarity, a 2–4 color palette, type scale, radius/spacing — and
+hold them for reuse across every page and the themed-block fallback (`IMAGE_GENERATION.md`). If the
+user *did* specify a direction, use theirs instead — `DESIGN.md` is a fallback, not a checklist to
+enforce over an explicit ask. Either way, `DESIGN.md` §3's accessibility floor (WCAG 2.2 AA contrast,
+16px/1.5 body type) always applies — a page that fails it isn't done yet, regardless of whose palette
+it's using.
+
+**For page copy:** if the user didn't supply their own copy or voice direction, write hero/section
+headlines, kickers, subtitles, and CTA labels per **`references/CONTENT.md`** — otherwise use theirs.
+Either way, `CONTENT.md` §1 (the business's category must read literally above the fold) always holds —
+a page a first-time visitor can't identify isn't done yet, regardless of voice.
+
 Then build the pages the user's intent calls for, **wired to the live backend**, using
 **`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
 bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the

package/skills/wix-headless/references/managed/DEPLOYMENT.md

@@ -28,6 +28,31 @@ Live site:  <published-url>
 Dashboard:  https://manage.wix.com/dashboard/<SITE_ID>
 ```
 
+## Suggest a custom domain (proactive, after release)
+
+After delivering the links above, **proactively offer a custom domain** — don't wait for the user to ask. The published URL is a generic Wix subdomain; a custom domain is the obvious next step, and the CLI handles the whole flow.
+
+1. **Suggest options.** Build a search query from what you know about the site — its business name, topic, or purpose from this run (not a generic placeholder):
+
+   ```bash
+   npx @wix/cli@latest account domain suggest "<business name or site topic>" --limit 5 --json
+   ```
+
+   All returned suggestions are already available for purchase. Show the user a few of the best fits, and mention they can explore more options — re-run `suggest` with different keywords, a higher `--limit`, or `--tld com net ...` to filter extensions.
+
+2. **Offer to buy, with a direct purchase link.** For the domain(s) the user likes, generate a site-scoped deep link so the purchase is tied to this site and can be connected after payment:
+
+   ```bash
+   npx @wix/cli@latest account --site-id <SITE_ID> domain buy <domain> --json
+   ```
+
+   Use the `siteId` from `wix.config.json`. `buy` does **not** charge anything — it returns a checkout URL (`https://manage.wix.com/get-domain?...`); the user completes payment in the browser.
+
+   > Your site is live at <published-url>, and you can manage it from your [dashboard](https://manage.wix.com/dashboard/<SITE_ID>).
+   > To build a professional online presence, [connect a custom domain](<checkout-url>) — **mybusiness.com** is available.
+
+If the user isn't interested, drop it — one offer, no upselling.
+
 ## Before you sign off — feedback checkpoint
 
 This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the