@wix/agent-skills 1.15.1 → 1.16.1

package/skills/wix-app/scripts/scan-a11y-eslint.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+// oxlint-disable no-console preserve-caught-error
+
+const path = require('path');
+const { createRequire } = require('module');
+
+const ROOT = process.cwd();
+const LOCAL_REQUIRE = createRequire(__filename);
+const ROOT_REQUIRE = createRequire(path.join(ROOT, 'package.json'));
+const { ESLint } = loadModule('eslint');
+const jsxA11y = loadModule('eslint-plugin-jsx-a11y');
+const tsParser = loadModule('@typescript-eslint/parser');
+
+const RULE_CONFIG = {
+  'jsx-a11y/alt-text': 'error',
+  'jsx-a11y/anchor-has-content': 'error',
+  'jsx-a11y/anchor-is-valid': 'error',
+  'jsx-a11y/aria-activedescendant-has-tabindex': 'error',
+  'jsx-a11y/aria-props': 'error',
+  'jsx-a11y/aria-proptypes': 'error',
+  'jsx-a11y/aria-role': 'error',
+  'jsx-a11y/aria-unsupported-elements': 'error',
+  'jsx-a11y/click-events-have-key-events': 'error',
+  'jsx-a11y/heading-has-content': 'error',
+  'jsx-a11y/iframe-has-title': 'error',
+  'jsx-a11y/img-redundant-alt': 'error',
+  'jsx-a11y/interactive-supports-focus': 'error',
+  'jsx-a11y/label-has-associated-control': 'error',
+  'jsx-a11y/media-has-caption': 'error',
+  'jsx-a11y/mouse-events-have-key-events': 'error',
+  'jsx-a11y/no-access-key': 'error',
+  'jsx-a11y/no-aria-hidden-on-focusable': 'error',
+  'jsx-a11y/no-autofocus': 'error',
+  'jsx-a11y/no-distracting-elements': 'error',
+  'jsx-a11y/no-interactive-element-to-noninteractive-role': 'error',
+  'jsx-a11y/no-noninteractive-element-interactions': 'error',
+  'jsx-a11y/no-noninteractive-element-to-interactive-role': 'error',
+  'jsx-a11y/no-noninteractive-tabindex': 'error',
+  'jsx-a11y/no-redundant-roles': 'error',
+  'jsx-a11y/no-static-element-interactions': 'error',
+  'jsx-a11y/prefer-tag-over-role': 'error',
+  'jsx-a11y/role-has-required-aria-props': 'error',
+  'jsx-a11y/role-supports-aria-props': 'error',
+  'jsx-a11y/scope': 'error',
+  'jsx-a11y/tabindex-no-positive': 'error',
+};
+
+function toRelative(filePath) {
+  return path.relative(ROOT, filePath) || filePath;
+}
+
+function severityLabel(severity) {
+  if (severity === 2) return 'error';
+  if (severity === 1) return 'warning';
+  return 'off';
+}
+
+function loadModule(name) {
+  try {
+    return LOCAL_REQUIRE(name);
+  } catch (localError) {
+    try {
+      return ROOT_REQUIRE(name);
+    } catch (rootError) {
+      throw new Error(
+        `Missing dependency "${name}". Local resolution failed: ${localError.message}. Root resolution failed: ${rootError.message}`,
+      );
+    }
+  }
+}
+
+function createEslint() {
+  try {
+    return new ESLint({
+      overrideConfigFile: true,
+      overrideConfig: [
+        {
+          files: ['**/*.{tsx,jsx,ts,js}'],
+          languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+              ecmaFeatures: { jsx: true },
+              ecmaVersion: 2022,
+              sourceType: 'module',
+            },
+          },
+          plugins: {
+            'jsx-a11y': jsxA11y,
+          },
+          rules: RULE_CONFIG,
+        },
+      ],
+    });
+  } catch (flatConfigError) {
+    try {
+      return new ESLint({
+        useEslintrc: false,
+        overrideConfig: {
+          parser: '@typescript-eslint/parser',
+          plugins: ['jsx-a11y'],
+          parserOptions: {
+            ecmaFeatures: { jsx: true },
+            ecmaVersion: 2022,
+            sourceType: 'module',
+          },
+          rules: RULE_CONFIG,
+        },
+        extensions: ['.tsx', '.jsx', '.ts', '.js'],
+      });
+    } catch (legacyConfigError) {
+      throw new Error(
+        `Failed to initialize ESLint. Flat config error: ${flatConfigError.message}. Legacy config error: ${legacyConfigError.message}`,
+      );
+    }
+  }
+}
+
+async function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.log(
+      JSON.stringify(
+        {
+          error: 'No files specified.',
+          usage: 'node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...',
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(1);
+  }
+
+  const absoluteFiles = files.map((f) => path.resolve(f));
+
+  const eslint = createEslint();
+
+  const results = await eslint.lintFiles(absoluteFiles);
+
+  const findings = [];
+  const parseErrors = [];
+
+  for (const result of results) {
+    const relFile = toRelative(result.filePath);
+
+    for (const msg of result.messages) {
+      if (msg.fatal) {
+        parseErrors.push({
+          file: relFile,
+          line: msg.line,
+          column: msg.column,
+          message: msg.message,
+        });
+        continue;
+      }
+
+      if (!msg.ruleId || !msg.ruleId.startsWith('jsx-a11y/')) continue;
+
+      findings.push({
+        file: relFile,
+        line: msg.line,
+        column: msg.column,
+        endLine: msg.endLine ?? null,
+        endColumn: msg.endColumn ?? null,
+        rule: msg.ruleId,
+        severity: severityLabel(msg.severity),
+        message: msg.message,
+      });
+    }
+  }
+
+  const ruleBreakdown = {};
+  for (const f of findings) {
+    ruleBreakdown[f.rule] = (ruleBreakdown[f.rule] || 0) + 1;
+  }
+
+  const output = {
+    meta: {
+      filesScanned: files.length,
+      engine: 'eslint + eslint-plugin-jsx-a11y',
+      rulesEnabled: Object.keys(RULE_CONFIG).length,
+      parseErrors,
+    },
+    findings,
+    summary: {
+      totalFindings: findings.length,
+      filesWithFindings: new Set(findings.map((f) => f.file)).size,
+      cleanFiles: files.length - new Set(findings.map((f) => f.file)).size,
+      ruleBreakdown,
+    },
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ error: err.message }, null, 2));
+  process.exit(1);
+});

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/CAPABILITIES.md

@@ -37,10 +37,23 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **Required site features:** an index/list view of the collection; a detail page per item. (Visitor reads are public; visitor writes go through a form.) **(Opt-in, with members)** when the brief asks for per-user-private data ("my saved items", a personal list) or member-only content **and** members login is in the run, a collection can instead be **member-scoped** — each member sees/edits only their own rows, or any logged-in member reads shared member-only content. Added only on that intent, never by default; see the members cross-cutting entry and `setup-cms.md`.
 - **Implementation checklist:** show each item's main fields with clear labels; link the list to each item's detail page; show a sensible empty state when there are no items yet.
 
-### forms — capture leads
-- **Intent:** contact / lead / signup / waitlist / "let people reach me" / generic custom data capture / nothing dynamic named. **Not for RSVP** — confirming attendance to an event or occasion (a wedding, party, or gathering) is the **events** vertical, which has a built-in RSVP registration form; route there even when it's a single occasion with no tickets. Use `forms` only when no event is involved.
+### forms — any visitor-fillable form
+- **Intent:** contact / enquiry / lead / signup / waitlist / application / feedback / survey /
+  questionnaire / quote request / intake or registration form / "let people reach me" / generic custom
+  data capture — plus the **floor** when nothing dynamic is named. Lead capture is the most common
+  case, **not the boundary**: any form a visitor fills in and submits is this vertical, and whether
+  the submission also becomes a CRM contact is an optional per-field mapping.
+- **Not forms — an RSVP is `events`:** confirming attendance to an event or occasion (a wedding,
+  party, or gathering) is the **events** vertical, which ships a built-in RSVP registration form —
+  route there even for a single occasion with no tickets.
+- **Not forms — a per-service booking form is `bookings`:** the form attached to a bookable service
+  belongs to **bookings**. Use `forms` only when neither an event nor a bookable service is
+  involved.
 - **Required site features:** a visible form; a confirmation after submitting; basic field validation.
-- **Implementation checklist:** render every field with a clear label; mark which fields are required; a clear submit button; show a thank-you / success state after sending; show a friendly message if the submit fails.
+  A site may have **more than one** form, each with its own purpose and field set.
+- **Implementation checklist:** render every field with a clear label; mark which fields are required;
+  a clear submit button; show a thank-you / success state after sending; show a friendly message if
+  the submit fails.
 
 ### events — events and registration
 - **Intent:** event / ticket / RSVP / registration / attendees / "confirm attendance" / a wedding, party, or gathering people respond to. **Covers RSVP to a single occasion** (one wedding, one party) — not only multi-event listings, and not only ticketed events. An invitation with an RSVP is this vertical, not `forms`.

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/SDK_HANDOFF.md

@@ -58,7 +58,7 @@ The host binds to **schema**, not to a frozen list of content IDs. **Content is
 
 Carry only the **structural** carve-outs the coding step genuinely reads — the collection/form *names and keys* you must know to query and bind, which do **not** change when an owner adds a row:
 - **cms:** `collectionId` + field keys per collection
-- **forms:** **`formId` only.** The field set, order, labels, `required`, validation format, and dropdown options are **read live from the form schema at render time** (visitor token, no elevate — `how-to-code-forms.md`), so the handoff no longer carries per-field `target` keys. Reading the schema live is the source of truth: it closes the seed↔site drift by construction (a field the owner adds/removes/relabels in the dashboard reflects on the site with no code change) and is the more v2-aligned "host resolves everything else live" shape. (For a bespoke, design-led form where dashboard-editability isn't the value prop, the host may still hardcode inputs from the known `target`s — `how-to-code-forms.md` covers that mode — but the default and the carry is `formId` only.)
+- **forms:** `formId` + each form's field `target` keys (the submission keys the frontend binds `name` = target). Field set, labels, options, and validation (`required`, format, length/pattern) are read live from the schema (`how-to-code-forms.md`).
 
 Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public `clientId` are needed too, but they're identical for every site, not seed output; they're in §2/§3.)
 

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

@@ -34,7 +34,7 @@ Each entry states only the entities, where their count/content comes from, the p
 - **stores** — *A product catalog.* Recipe: **`setup-online-store.md`**. `intent.stores.productCount` products whose names/prices fit `brand`. If `intent.stores.categoriesNamed` is non-empty, create exactly those categories and assign products into them; **if empty, create none** (skill policy — overrides any docs default). **Variant cardinality — keep it small by default:** unless `intent.stores` calls for specific options, give each product **at most one option with ≤3 choices** (so ≤3 variants/product); many products legitimately have **no** options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but **honor a larger/explicit option set when intent names one** (this default is a floor, not a cap). Text-only by default (images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `categoryIds[]` to assign products into their categories; **nothing goes to the handoff** — the frontend lists products and categories **live** (`queryProducts` / `searchProducts` / `queryCategories`), so owner-added products/categories appear with no code change.
 - **blog** — *Initial posts.* Recipe: **`setup-blog.md`**. `intent.blog.postCount` posts on `intent.blog.topics` (or brand-derived topics). Text-only (no covers). **Keep:** nothing for the handoff — posts are discovered **live** (`queryPosts`, `[...slug]` routes). Track created post ids only transiently (to confirm success / assign categories).
 - **cms** — *Content collections.* Recipe: **`setup-cms.md`**. One collection per `intent.cms.collections` entry; `itemCount` items each, content from `brand`. Collections are **public-read** (visitor reads on the frontend) by default. **(Opt-in, members only)** if the brief calls for per-user-private or member-only data **and** members login is in the run, seed that collection **member-scoped** instead (per-user or member-only — see `setup-cms.md`); a per-user collection is seeded **empty** (members populate it), since admin-seeded rows are owned by the admin. **Keep (→ handoff):** `collectionIds{<name>}` + each collection's **field keys** — this is *structural* (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). `itemIds{<name>:[]}` only transiently, for wiring multi-references during seeding.
-- **forms** — *Lead-capture forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry; `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend sets input `name` = target to submit).
+- **forms** — *Visitor-fillable forms.* Recipe: **`setup-forms.md`**. One form per `intent.forms.forms` entry; fields from the entry, `purpose` names the form. **Keep (→ handoff):** `formIds[]` + each form's field **`target`** keys — *structural* (the frontend binds each input's `name` = target to submit; targets are **immutable**, so they don't go stale when an owner relabels a field).
 - **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
 - **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
 - **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).

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 }] } },
 });
 ```