@wix/agent-skills 1.35.1 → 1.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.35.1",
+  "version": "1.36.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/references/CODE_QUALITY.md

@@ -8,7 +8,7 @@ Applies to all generated code across every Wix CLI app extension type. Each per-
 - Prefer type-narrowing and exhaustive logic over assertions; avoid non-null assertions (`!`) and unsafe casts (`as any`).
 - Treat optional values, refs, and array indexing results as possibly undefined and handle them explicitly.
 - Use exhaustive checks for unions (e.g., `switch` with a `never` check) and return total values (no implicit `undefined`).
-- Do NOT use `// @ts-ignore` or `// @ts-expect-error`; fix the types or add guards instead.
+- Do NOT use `// @ts-ignore` or `// @ts-expect-error`; fix the types or add guards instead. The one exception is a `// @ts-ignore` directly above an import of a context provider's hook by its `moduleSpecifier`: TypeScript cannot resolve that specifier, because the site's import map supplies it only at runtime.
 
 ## Core Principles
 

package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md

@@ -21,18 +21,17 @@ Supplementary files are allowed; keep scaffold roles intact.
 
 ## Required Reading (blocking)
 
-Before writing code, open and read in full every reference in the matching
-row. An unopened one is a failed run. Open paths directly; never skim or
-grep instead.
+Before writing code, read every reference in the matched row in full.
+Unopened references fail the run—open paths directly; no skim or grep.
 
 | Scope | Required references |
 | --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`VISUAL-QUALITY.md`](editor-react-component/VISUAL-QUALITY.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
 | Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
 | Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
 | Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`VISUAL-QUALITY.md`](editor-react-component/VISUAL-QUALITY.md) |
 | Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
 | Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
 | Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
@@ -47,14 +46,13 @@ grep instead.
    ```
 
    Never rerun the scaffold for an existing component.
-   Write a meaningful `description` in 1-2 plain sentences (max 300 chars): what
-   the user sees, when to use it, and capabilities that affect that choice.
-   Don't repeat the name or add implementation details.
+   Write a meaningful `description` (max 300 chars, 1-2 sentences): what users see,
+   when to use it, and capability tradeoffs—no name repeat or implementation detail.
 
 2. **Run the dependency preflight.**
 
    ```bash
-   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
+   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types clsx deepmerge-ts)
    dev=(@babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core)
 
    node - "${deps[@]}" "${dev[@]}" <<'JS' || {
@@ -63,7 +61,7 @@ grep instead.
      .map(p => p.replace(/@<7$/, ''))
      .filter(p => !require.resolve.paths(p)?.some(d => fs.existsSync(path.join(d, p, 'package.json'))));
    if (missing.length) {
-     console.error(`Missing dependencies: ${missing.join(', ')}`);
+     console.error(`Missing: ${missing.join(', ')}`);
      process.exit(1);
    }
    JS
@@ -74,27 +72,26 @@ grep instead.
    }
    ```
 
-3. **Plan.** Identify props, root, parts, and states; open all required references first.
-   Use them and the scaffold before inspecting package declarations; inspect
-   only for undocumented APIs or fields, or typecheck failures. Declarations
-   govern API shapes; retain editor rules.
+3. **Plan.** Identify props, root, parts, and states; open required references first.
+   Use them and the scaffold before package declarations—only for undocumented APIs
+   or typecheck failures. Declarations govern API shapes; keep editor rules.
 
 4. **Implement.** Keep props, logic, and styles in their scaffolded editable
    files. Format edited source files with the app's formatter. Never edit or format `*.generated.ts`.
 
-5. **Run the accessibility review (mandatory).** Once the JSX is complete, run from the
-   same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
+5. **Run the a11y review (mandatory).** After JSX, run from the
+   same folder (`<SKILL_ROOT>` contains the active `SKILL.md`):
 
    ```bash
    node <SKILL_ROOT>/scripts/scan-a11y-review.cjs src/extensions/site/components/<component-name>
    ```
 
-   Follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
+   Follow [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
    rerun at most twice, then report remaining findings.
 
 6. **Configure the editor extension.** For creation or a requested sizing,
    installation, or manifest change, apply
-   [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
+   [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
    to the extension; otherwise leave it unchanged. Synchronize preview
    `requiredDataFields` and `rootClassName`.
 
@@ -105,15 +102,15 @@ grep instead.
    npx wix build && npx wix generate manifest
    ```
 
-   Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility review.
+   Run `npx tsc --noEmit`, relevant tests/lint, and the a11y review.
    If later edits affect a check, rerun that check. Inspect the manifest when generated; never hand-repair it.
    Diagnose failures with
-   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
+   [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
-   For creation/layout changes, complete the routed overflow resize review.
+   For creation/layout changes, run the overflow resize review.
 
-8. **Report.** Summarize files, checks, blockers, unrun checks.
-   List required references as read/unread; read any unread one and fix first.
+8. **Report.** Summarize files, checks, blockers, and skipped checks.
+   List references read/unread; fix unread before closing.
 
 ## Reference Policy
 
@@ -133,10 +130,11 @@ trigger. Preserve unrelated behavior. References are leaves.
 | Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
 | Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
+| Owner-replaceable icon/SVG (not fixed UI glyphs) | [`VECTOR-ART.md`](editor-react-component/VECTOR-ART.md) |
 
 ## Non-Negotiables
 
-- React 18 only; do not assume React 19 runtime features.
+- React 18 only; no React 19 runtime features.
 - Include typed `id`, `className`, `direction`, and `a11y` support.
 - Elected root: `dir={direction}`, fallback-direction class, logical CSS for
   direction-sensitive layout.
@@ -148,13 +146,13 @@ trigger. Preserve unrelated behavior. References are leaves.
 - Named parts: global class, module class, and `elementProps` (root uses
   top-level props).
 - Every visible text: a text prop plus a named part; no JSX text literals.
-- Native design states: interactive elements only, never a non-interactive root
-  or part; pair selectors with injected modifiers; toggle custom state classes
-  from data, each with a matching `:global()` rule.
+- Native design states: interactive elements only; pair selectors with injected
+  modifiers. Custom states need a class toggle from logic or data, or a root prop
+  trigger; styled states need matching `:global()` rules.
 - Open/close/reveal: props-only root
   `isOpen: ElementState<boolean>` synced to state; module classes, no `--open` class.
-- Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
-  all bodies, hide inactive accessibly.
+- Single-visible-body arrays: `ActiveItemIndex<'prop'>`, render all bodies,
+  hide inactive accessibly; item `name` only when rendered.
 - No arrays inside array items; keep group fields flat (no object props).
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.

package/skills/wix-app/references/editor-react-component/ANIMATED-COMPONENTS.md

@@ -197,7 +197,7 @@ Wire the named part completely:
 <button
   type="button"
   {...elementProps?.myAnimationPlayButton}
-  className={classNames(
+  className={clsx(
     'my-animation-play-button',
     styles.playButton,
     elementProps?.myAnimationPlayButton?.className,

package/skills/wix-app/references/editor-react-component/COMPONENT-CONTRACT.md

@@ -43,12 +43,12 @@ Rules:
   when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
 - Use a native link for a CTA with a real `href`, or a native button for an
-  action. Never fall back to `href="#"`: it has no meaningful destination.
+  action. Never use `href="#"`: it has no destination.
 
 ## Numeric Range Constraints
 
-Use inline `@min` and `@max` JSDoc tags for fixed-domain numeric props. Manifest
-generation reads the tags automatically.
+Use inline `@min`, `@max` JSDoc tags for fixed-domain numeric props. Manifest
+generation reads them automatically.
 
 ```ts
 export type RatingProps = {
@@ -57,12 +57,12 @@ export type RatingProps = {
 };
 ```
 
-Use fixed bounds for ratings, percentages, playback speed, columns, etc. Omit
-for open-ended values or indices tied to a dynamic collection.
+Use for ratings, percentages, columns; omit for open-ended values or indices
+tied to a dynamic collection.
 
 ## Named Parts and `elementProps`
 
-Treat an independently editable inner element as a named part. Wiring rules:
+An independently editable inner element is a named part:
 
 - Root receives top-level `id`, `className`, `direction`, `a11y` — no
   `elementProps` entry.
@@ -75,7 +75,7 @@ On a raw HTML element, spread the entry and explicitly merge its injected
 ```tsx
 <a
   {...elementProps?.planCardCta}
-  className={classNames(
+  className={clsx(
     'plan-card-cta',
     styles.cta,
     elementProps?.planCardCta?.className,
@@ -118,12 +118,12 @@ does not inherit the component's direction.
 
 ### Array Props
 
-Array elements must be objects with named keys for semantics and extensibility.
+Array elements must be objects with named keys for semantics and extensibility. Always declare array-item fields optional.
 
 ```ts
 type GalleryProps = {
-  images: Array<{ image: Image; caption?: string }>;
-  tags: Array<{ label: string }>;
+  images: Array<{ image?: Image; caption?: string }>;
+  tags: Array<{ label?: string }>;
 };
 ```
 
@@ -131,22 +131,25 @@ Do not export `Array<string>`, `Array<Image>`, `Array<Array<T>>`, or nested
 arrays inside items.
 
 The parent owns the array. Item sub-components receive one item, not the
-collection. Do not add an `id` field for React keys—use the item's semantic
-named fields instead. Prefer: (1) a stable unique field (`value`, `uri`, `label`, …), (2)
-else slug a user-facing string (`name`, `label`), (3) else the array index.
+collection. Do not add an `id` field for React keys—use semantic named fields.
+Prefer: (1) a stable unique field (`value`, `uri`, `label`, …), (2) else slug a
+user-facing string (`name`, `label`), (3) else the index.
 
 ## Active-Item Components
 
-Apply this contract when an array-driven UI shows one item body at a time (tabs,
-slides, steps). Skip for always-visible lists, multi-select, or multi-expand.
+Apply when an array-driven UI shows one item body at a time (tabs, slides,
+steps). Skip for always-visible lists, multi-select, or multi-expand.
 
-- Every item needs `name: string` (used for hat-selector labels).
+- Declare `name` only when a part renders it; the hat shows `name`, else
+  "Item N". A visible per-item trigger label (tabs, steps) is the `name` field.
+  Slides, cards, carousels with no per-item label: no `name`. Never declare an
+  item field no part renders.
 - **Import and use `ActiveItemIndex<'arrayPropName'>`** from
   `@wix/react-component-utils`. The type argument must match the array prop name
   exactly, and `defaultProps` must set the index to `0`.
-- Render all bodies with `.map()`. Active body gets --active; inactive bodies get functional CSS visibility, aria-hidden, and inert.
-- With React 18 types, spread `...(!isActive ? { inert: 'true' } : {})` onto an inactive body; this emits the boolean HTML attribute without a TypeScript prop error. Use the app's typecheck instead of a scratch TypeScript project.
-- Provide keyboard navigation and the matching ARIA pattern.
+- Render all bodies with `.map()`. Active body gets `--active`; inactive bodies get CSS visibility, `aria-hidden`, and `inert`.
+- React 18 types: spread `...(!isActive ? { inert: 'true' } : {})` onto an inactive body; it emits the boolean attribute without a type error. Typecheck with the app, not a scratch project.
+- Keyboard navigation and the matching ARIA pattern.
 
 ```ts
 import type { A11y, Direction } from '@wix/editor-react-types';
@@ -180,7 +183,7 @@ one representation of it.
 Common fields in the installed types: `Image` has required `url: string` and
 optional `uri`, `alt`, `width`, `height`; `Link` has optional `href`, `target`
 (`'_self' | '_blank'`), and `rel`. Use `image.url` for `<img src>`,
-`image.alt` for its alternative text, and `link.href` for `<a href>`.
+`image.alt` for alt text, and `link.href` for `<a href>`.
 
 Do not represent media as a URL/source string or split its metadata across
 primitive props. Preserve the media object through the public contract so the
@@ -216,7 +219,7 @@ export const defaultProps = {
 ```
 
 Use distinct Wix-hosted defaults per image slot; keep all fallback data in
-`defaultProps` so rendering never hardcodes a second fallback in JSX.
+`defaultProps` so JSX never hardcodes a second fallback.
 
 Use this pool in order, cycling only when more than five defaults are needed:
 
@@ -228,8 +231,6 @@ Use this pool in order, cycling only when more than five defaults are needed:
 | 4 | `11062b_45e67783d39c4963ab9e4fc418173233~mv2.jpg` | Abstract pink waves |
 | 5 | `11062b_4c11f014b0d04948b2e6f554076bc40a~mv2.jpg` | Coastal village aerial |
 
-For one image use entry 1; for multiple slots use a different entry each.
-
 ## Internal File Splitting
 
 Split independently understandable units when it makes the main component easier
@@ -248,7 +249,7 @@ component-name/
 └── component-name.module.css
 ```
 
-Do not extract tiny fragments merely to satisfy a line-count threshold.
+Do not extract tiny fragments just to pass a line-count threshold.
 
 ## Checklist
 
@@ -256,7 +257,7 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 - [ ] Props hold authored data/behavior; derived values stay internal.
 - [ ] Fixed-domain numeric props use `@min`/`@max` JSDoc tags.
 - [ ] Named inner parts have `elementProps` wiring; leaf components avoid exported `children`.
-- [ ] One-body-visible arrays use the active-item contract and render all bodies.
+- [ ] One-body-visible arrays use the active-item contract and render all bodies; `name` only when a part renders it.
 - [ ] Array elements are objects with semantic named fields. No separate `id` field added to item types; React keys use item fields (stable unique → slug → index), not a typed `id`.
 - [ ] Authored media uses the corresponding Wix media type, not URL/source strings or flattened metadata.
 - [ ] Defaults live only in the props file (no JSX fallbacks).

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -3,9 +3,6 @@
 Use these rules for the scaffolded `<component-name>.module.css` file and any
 colocated CSS Modules owned by internal sub-components.
 
-**Visual intent.** When the request specifies how the component should look —
-mood, palette, layout style, or a reference — follow that direction. Default to a modern, refined look — intentional layout, pleasing proportions, polished and deliberate styling.
-
 ## Contents
 
 - [Classes and Named Parts](#classes-and-named-parts)
@@ -15,12 +12,11 @@ mood, palette, layout style, or a reference — follow that direction. Default t
 - [Responsiveness and Direction](#responsiveness-and-direction)
 - [Editable Values](#editable-values)
 - [Interaction and Motion](#interaction-and-motion)
-- [Default Visual Quality](#default-visual-quality)
 - [Checklist](#checklist)
 
 ## Classes and Named Parts
 
-Apply classes with `classnames`:
+Apply classes with `clsx` (`import clsx from 'clsx'`):
 
 | Element | Classes |
 | --- | --- |
@@ -37,7 +33,7 @@ spread its `elementProps` entry and merge the injected class.
 ```tsx
 <h2
   {...elementProps?.profileCardHeading}
-  className={classNames(
+  className={clsx(
     'profile-card-heading',
     styles.heading,
     elementProps?.profileCardHeading?.className,
@@ -71,11 +67,11 @@ Do not use compound selectors, tag selectors, child/sibling combinators, or CSS
 nesting for editable styling. They make an element's editor surface depend on
 DOM context.
 
-Narrow exception: a relationship selector may control behavior-only visibility
-when the behavior requires ancestor state and the rule does not define editable
-appearance. A hover-revealed play/pause control is the canonical case. Keep all
-of the control's size, color, border, typography, and state styling on its own
-single-class rules.
+Narrow exceptions, neither defining editable appearance: a relationship
+selector for behavior-only visibility that needs ancestor state (a
+hover-revealed play/pause control), and an icon part's layout-only `svg` rule
+(`VECTOR-ART.md`). Keep each control's size, color, border, typography, and state
+styling on its own single-class rules.
 
 ## Root Layout
 
@@ -218,11 +214,14 @@ per icon (`--start-icon-size`), applied via `inline-size`/`block-size` and
 }
 ```
 
+- **Replaceable**: follow `VECTOR-ART.md`.
+
 ## Interaction and Motion
 
 - Set `pointer-events: auto` on the root and each interactive element.
-- Pair native interaction selectors with the matching editor-injected global
-  state modifier. Toggle custom state modifiers from component data.
+- Pair native design states (`hover`, `focus`, `disabled`, `invalid`) with
+  the matching editor-injected global modifier. Custom modifiers need a class
+  toggle from component logic/data or a root prop trigger (`DESIGN-STATES.md` §5).
 - Do not add decorative transitions or animations.
 - When motion is functionally required, list the exact transition properties;
   never use `transition: all` or an implicit `all` shorthand.
@@ -233,32 +232,6 @@ per icon (`--start-icon-size`), applied via `inline-size`/`block-size` and
 }
 ```
 
-## Default Visual Quality
-
-Create a clear hierarchy with at least two techniques that fit the component:
-a defined surface, border or soft shadow, type scale or weight, spacing, an
-accent, or visible interaction states. Use these neutral defaults unless the
-request or existing design provides better values:
-
-- 16px or larger body text, 14px or larger labels, and 600–700 weight for titles
-- 8–16px spacing inside controls and 16–32px spacing inside containers
-- 8–12px corner radii for cards and controls; `50%` for circular media
-- a subtle border or soft shadow when a card, panel, or control needs separation
-- touch targets at least 44 by 44px and visible keyboard focus states
-
-### Foreground and Background Ownership
-
-If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. An inline control meant to blend in (link, ghost button, icon button) may leave it transparent.
-
-- On a transparent root, don't hardcode text or icon colors; inherit them from the parent.
-- Set the background and main text/icon color together on the same element. Any secondary text (captions, hints, icons) must still be readable against that same background.
-- If an interactive state changes the background, set the foreground color in that state too. Don't assume a color inherited from a parent or from a previous state will still look right on the new background.
-- In every default and interactive state, meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI controls.
-
-A neutral owned surface may use a light background with dark primary and
-secondary foregrounds, plus one accessible accent. The exact colors are not a
-contract; the contrast relationship is.
-
 ## Checklist
 
 - [ ] The scaffolded component and each extracted internal sub-component own
@@ -273,8 +246,5 @@ contract; the contrast relationship is.
 - [ ] Every part that sets `font-size` also sets `font-family`, on the part that
       should own the typography control.
 - [ ] Interactive elements expose pointer events and accessible design states.
-- [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
-- [ ] Every explicit foreground has a known contrasting background; transparent
-      components inherit foregrounds from their host.
 - [ ] No unexposed descendant paints an opaque surface; promote it to a named
       part instead.

package/skills/wix-app/references/editor-react-component/DESIGN-STATES.md

@@ -6,16 +6,6 @@ eligible interaction (`hover`, `focus`, `disabled`, `invalid`) or per a
 selectable value in its data (`selected`, `active`, `checked`, …). Author states
 in the component's `.tsx` and `.module.css`.
 
-## Contents
-
-- [Choose Supported States](#1-choose-supported-states)
-- [Name the State Class](#2-name-the-state-class)
-- [Author CSS](#3-author-css)
-- [Wire React](#4-wire-react)
-- [Use Prop-Triggered States on the Root Only](#5-use-prop-triggered-states-on-the-root-only)
-- [Expose Open/Collapsed Toggles](#6-expose-opencollapsed-toggles)
-- [Checklist](#checklist)
-
 ## 1. Choose Supported States
 
 | Element | Author these states |
@@ -48,7 +38,7 @@ Flat: the element's own global class + `--<state>`. Because inner-part
 global classes are prefixed with the component name, the state class is prefixed too —
 e.g. `pricing-card-cta--hover`, `pricing-card-plan-row--selected`. Never bare
 (`cta--hover` collides with other components) and never
-nested (`card__row--selected`).
+nested (`card__row--selected`). Add it only to an element that has its base class.
 
 ## 3. Author CSS
 
@@ -58,7 +48,7 @@ state selector. When both set the same property, write the state selector
 value as the part's resting `defaultValue`, even though runtime CSS renders
 correctly.
 
-- **Native design state** — pair the pseudo-class with the `:global` modifier.
+- **Native (`hover`, `focus`, `disabled`, `invalid`)** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
   split the pair across states. A standalone `:focus-visible` accessibility
   rule on a non-input control is not an editor design state and has no global
@@ -101,10 +91,9 @@ The local static accessibility scan cannot measure rendered color contrast.
 - **Native** — render the correct interactive element (`<button>`, an
   interactive `role`, or a handler). No custom state class is needed, but the
   element must still satisfy the accessibility contract for its semantics.
-- **Custom** — toggle the global state class from the element's data, except
-  for open/collapsed content (§6). Every state class toggled in TSX needs a
-  matching `:global()` rule in §3; without one the manifest generator silently
-  drops the state.
+- **Custom** — each `:global()` state rule must have a matching class toggle
+  driven by component logic or data, or a root prop trigger (§5). Open/collapsed
+  content uses §6.
 - **Inner elements** — every named inner element gets an `elementProps` entry;
   spread it so editor-driven states reach it. On a raw HTML element also merge
   `elementProps?.<key>.className` inline; on a skill-built sub-component the
@@ -115,14 +104,14 @@ The local static accessibility scan cannot measure rendered color contrast.
 <button
   type="button"
   {...elementProps?.pricingCardCta}
-  className={classNames('pricing-card-cta', styles.cta, elementProps?.pricingCardCta?.className)}
+  className={clsx('pricing-card-cta', styles.cta, elementProps?.pricingCardCta?.className)}
 >
   {label}
 </button>
 
 <li
   {...elementProps?.pricingCardPlanRow}
-  className={classNames(
+  className={clsx(
     'pricing-card-plan-row',
     styles.planRow,
     row.selected && 'pricing-card-plan-row--selected',
@@ -205,7 +194,7 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
   {...elementProps?.infoPanelContent}
   aria-hidden={!open}
   {...(!open && { inert: '' })}
-  className={classNames(
+  className={clsx(
     'info-panel-content',
     styles.content,
     open && styles.contentOpen,
@@ -229,7 +218,7 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
 - [ ] Non-input controls retain a standalone `:focus-visible` keyboard indicator.
 - [ ] Custom state classes are flat, global, and prefixed by component and part.
 - [ ] Named inner parts spread and merge their `elementProps` entry.
-- [ ] Every state class toggled in TSX has a matching `:global()` CSS rule.
+- [ ] Custom CSS state rules and their class toggles or root prop triggers match.
 - [ ] `ElementState<boolean>` is used only for a component-level root state.
 - [ ] An open/collapsed component exposes a props-only `isOpen` root state,
       syncs internal state from it, always renders its content, and adds no

package/skills/wix-app/references/editor-react-component/MANIFEST-ERRORS.md

@@ -23,12 +23,13 @@ After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.
 ## Warnings
 
 The build can also print non-fatal warnings such as
-`[css] … styles selectors that matched no element in the extraction render`.
+`.item is missing from initial render (<file>)`.
 Read every warning and fix it; this is mandatory, with one exception below.
 
-- **A part's own class** (`.errorMessage`, `.item`) means the part is not
-  mounted in the extraction render. Keep it mounted per `PARTS.md`, then
-  re-run build and manifest generation.
+- **A `.tsx` file in parentheses**, or **a part's own class** (`.errorMessage`,
+  `.item`) in a `.css` file, means the part is not mounted in the extraction
+  render. Keep it mounted and hide it with `hidden` or CSS per `PARTS.md`,
+  then re-run build and manifest generation.
 - **A class applied only by state** (`.contentOpen` from `open && styles.contentOpen`)
   is expected: the part is mounted and only the state look is absent. Leave the
   markup and CSS unchanged; do not force the state on or remove the styling.

package/skills/wix-app/references/editor-react-component/PARTS.md

@@ -71,7 +71,7 @@ const item = current ?? placeholderItem; // placeholder shows only while hidden
 <div hidden={phase !== 'question'}>
   <h3
     {...elementProps?.quizQuestion}
-    className={classNames('quiz-question', styles.question, elementProps?.quizQuestion?.className)}
+    className={clsx('quiz-question', styles.question, elementProps?.quizQuestion?.className)}
   >
     {item.question}
   </h3>

package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md

@@ -32,7 +32,7 @@ Use this pattern:
 ```tsx
 <div
   {...elementProps?.audioPlayerProgressBar}
-  className={classNames(
+  className={clsx(
     'audio-player-progress-bar',
     styles.progressBar,
     elementProps?.audioPlayerProgressBar?.className,

package/skills/wix-app/references/editor-react-component/VECTOR-ART.md

@@ -0,0 +1,95 @@
+# Vector Art
+
+Use this reference when a component shows an icon or other SVG the site owner
+can replace. Fixed glyphs stay inline per
+CSS-GUIDELINES.md "SVG Icons".
+
+## The Prop
+
+Import `VectorArt` from `@wix/editor-react-types`. All fields are required; keep
+the whole object, never flatten it to a URL string.
+
+Declare it at the top level or as an array-item field, never in `elementProps`,
+which stays `className` only:
+
+```ts
+export type FeatureRowProps = {
+  icon?: VectorArt;
+  elementProps?: { featureRowIcon?: { className?: string } };
+};
+```
+
+## Render and Style
+
+The icon is a named part per `PARTS.md`. Inject `svgContent` unmodified (no
+`.replace()` or added attributes). Mark it `aria-hidden="true"` beside a visible label, or name the
+control with `a11y.ariaLabel` per `ACCESSIBILITY.md`.
+
+```tsx
+{icon && (
+  <span
+    {...elementProps?.featureRowIcon}
+    className={clsx('feature-row-icon', styles.icon, elementProps?.featureRowIcon?.className)}
+    aria-hidden="true"
+    dangerouslySetInnerHTML={{ __html: icon.svgContent }}
+  />
+)}
+```
+
+Declare the controls per CSS-GUIDELINES.md "SVG Icons", plus `--icon-rotation`
+via `rotate`. Add no border, background, or padding.
+
+```css
+.icon {
+  --icon-size: 24px;
+  --icon-color: #116dff;
+  --icon-rotation: 0deg;
+  display: block;
+  inline-size: var(--icon-size);
+  block-size: var(--icon-size);
+  fill: var(--icon-color);
+  rotate: var(--icon-rotation);
+}
+
+.icon svg {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+```
+
+With several icons, give each part its own class and prefixed properties;
+shared names merge into one control. Only the property-free `svg` rule may be
+shared (`.startIcon svg, .endIcon svg`).
+
+## Defaults
+
+Populate all six fields in `defaultProps`; keep them there, with no second
+fallback in JSX. Never invent a `uri` or use a `data:` URI.
+
+```ts
+export const defaultProps = {
+  icon: {
+    uri: '417ddd_00f94d35a8f84b959241a5d4293ee772.svg',
+    viewBox: '0 0 200 200',
+    contentBox: '10 10 180 180',
+    colors: {},
+    contentType: 'shape',
+    svgContent:
+      '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" data-type="shape"><path d="M100 190c49.706 0 90-40.294 90-90s-40.294-90-90-90-90 40.294-90 90 40.294 90 90 90"/></svg>',
+  },
+} as const satisfies Omit<FeatureRowProps, 'id' | 'className'>;
+```
+
+For further slots substitute `uri` and the path `d` (same `viewBox` and `contentBox`):
+
+| `uri` | Shape | path `d` |
+| --- | --- | --- |
+| `417ddd_3d6ddf28b43e45499ea8557b8d963c79.svg` | Arch | `M100 10c49.704 0 90 37.654 90 84.102V190H10V94.102C10 47.654 50.294 10 100 10` |
+| `417ddd_c4e65c20d3844ffd97c9b2551ce7d269.svg` | Heptagon | `m100 10 72.174 35.651L190 125.76 140.054 190H59.946L10 125.759l17.826-80.108z` |
+
+## Checklist
+
+- [ ] A replaceable icon is a `VectorArt` prop, not an inline `<svg>` or URL string.
+- [ ] Each icon is its own named part injecting `svgContent` unmodified, with prefixed `--icon-*` properties.
+- [ ] `defaultProps` carries all six fields with a `uri` from the pool.

package/skills/wix-app/references/editor-react-component/VISUAL-QUALITY.md

@@ -0,0 +1,39 @@
+# Visual Quality
+
+Use this reference for a component's default look: hierarchy, spacing, and
+foreground/background contrast.
+
+**Visual intent.** When the request specifies how the component should look —
+mood, palette, layout style, or a reference — follow that direction. Default to a modern, refined look — intentional layout, pleasing proportions, polished and deliberate styling.
+
+## Default Visual Quality
+
+Create a clear hierarchy with at least two techniques that fit the component:
+a defined surface, border or soft shadow, type scale or weight, spacing, an
+accent, or visible interaction states. Use these neutral defaults unless the
+request or existing design provides better values:
+
+- 16px or larger body text, 14px or larger labels, and 600–700 weight for titles
+- 8–16px spacing inside controls and 16–32px spacing inside containers
+- 8–12px corner radii for cards and controls; `50%` for circular media
+- a subtle border or soft shadow when a card, panel, or control needs separation
+- touch targets at least 44 by 44px and visible keyboard focus states
+
+### Foreground and Background Ownership
+
+If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. An inline control meant to blend in (link, ghost button, icon button) may leave it transparent.
+
+- On a transparent root, don't hardcode text or icon colors; inherit them from the parent.
+- Set the background and main text/icon color together on the same element. Any secondary text (captions, hints, icons) must still be readable against that same background.
+- If an interactive state changes the background, set the foreground color in that state too. Don't assume a color inherited from a parent or from a previous state will still look right on the new background.
+- In every default and interactive state, meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI controls.
+
+A neutral owned surface may use a light background with dark primary and
+secondary foregrounds, plus one accessible accent. The exact colors are not a
+contract; the contrast relationship is.
+
+## Checklist
+
+- [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
+- [ ] Every explicit foreground has a known contrasting background; transparent
+      components inherit foregrounds from their host.

package/skills/wix-docs/references/CALLING.md

@@ -68,7 +68,7 @@ Append `.md` to read:
 - [`rest-api-authentication`](https://dev.wix.com/docs/api-reference/articles/authentication/rest-api-authentication) — headers, token kinds
 - [`retrieve-tokens`](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens) — the `/oauth2/token` contract, all grant types
 - [`about-authentication`](https://dev.wix.com/docs/go-headless/authentication/about-authentication) — visitor vs member sessions
-- [`create-an-oauth-app-for-visitors-and-members`](https://dev.wix.com/docs/go-headless/getting-started/setup/authentication/create-an-oauth-app-for-visitors-and-members) — where the client id comes from
+- [`create-oauth-app`](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-oauth-app) — where the client id comes from
 - [`set-up-a-headless-client`](https://dev.wix.com/docs/go-headless/authentication/setup/set-up-a-headless-client) — wiring the client
 
 ## Dynamic Site Context — "what IS this site?"

package/skills/wix-headless-kit/guides/api-run.md

@@ -69,7 +69,7 @@ visitor tokens only, which cover what a visitor may see and nothing here.
 
 Unchanged from SKILL.md step 2 and its Verticals table: the brief names the business, the table
 names the solutions it needs. Read each solution's `{TEMPLATES}/{solution}/INSTRUCTIONS.md` for
-what it covers and `{TEMPLATES}/{solution}/seed/SEED.md` for what a seeded site holds.
+what it covers and `{TEMPLATES}/{solution}/seed/SEED.md` (`{solution}` is the template folder name, e.g. `storefront`, `bookings`) for what a seeded site holds.
 
 A brief that needs no solution (a game, a landing page, a tool) is a run of two steps: the site
 (step 2, with no `seedOptions`) and the frontend (step 5). No apps, no seed.

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.35.1"
+    "ref": "v1.36.0"
   }
 }

package/skills/wix-headless-templates/blog/seed/seed-blog.mjs

@@ -118,7 +118,7 @@ export async function installBlogApp(ctx) {
 
 // Every post create needs a REAL author memberId — a fabricated id fails with
 // "memberIds ... do not exist". A provisioned site has the owner as members[0].
-// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members/list-members.md
+// docs: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/list-members.md
 export async function getAuthorMemberId(ctx) {
   const r = await req(ctx, "/members/v1/members?fieldsets=PUBLIC&paging.limit=1", { method: "GET" });
   const id = r.members?.[0]?.id;

package/skills/wix-headless-templates/donations/app/wix/donations/campaigns.ts

@@ -22,7 +22,6 @@ const settingsApi = wixModule(ecommerceSettings);
 // The metrics list is EMPTY on a campaign nobody has donated to yet, and the campaign entity carries
 // formatted amounts but no currency code — so a fresh site would format nothing. The site's currency
 // comes from the eCommerce settings then (BUSINESS_INFO), read once per process; "" when refused.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 let siteCurrencyPromise: Promise<string> | null = null;
 function siteCurrency(): Promise<string> {
   siteCurrencyPromise ??= settingsApi

package/skills/wix-headless-templates/donations/app/wix/donations/donate.ts

@@ -6,7 +6,7 @@
 // (shared with the REST twin); this file is the transport only. Copy as-is.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md
 import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";

package/skills/wix-headless-templates/donations/project/src/wix/donations/campaigns.ts

@@ -22,7 +22,6 @@ const settingsApi = wixModule(ecommerceSettings);
 // The metrics list is EMPTY on a campaign nobody has donated to yet, and the campaign entity carries
 // formatted amounts but no currency code — so a fresh site would format nothing. The site's currency
 // comes from the eCommerce settings then (BUSINESS_INFO), read once per process; "" when refused.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 let siteCurrencyPromise: Promise<string> | null = null;
 function siteCurrency(): Promise<string> {
   siteCurrencyPromise ??= settingsApi

package/skills/wix-headless-templates/donations/project/src/wix/donations/donate.ts

@@ -6,7 +6,7 @@
 // (shared with the REST twin); this file is the transport only. Copy as-is.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md
 import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";

package/skills/wix-headless-templates/donations/rest/campaigns.ts

@@ -16,7 +16,6 @@ const BASE = "/donation-campaigns/v2/donation-campaigns";
 // A campaign nobody has donated to yet has no metrics entry, and the entity carries no currency code:
 // the site's currency then comes from the eCommerce settings, read once.
 // GET /_api/ecommerce-settings/v1/ecommerce-settings?fields=BUSINESS_INFO → { ecommerceSettings: { businessInfo: { currency } } }
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 let siteCurrencyPromise: Promise<string> | null = null;
 function siteCurrency(): Promise<string> {
   siteCurrencyPromise ??= wixRequest<Raw>("/_api/ecommerce-settings/v1/ecommerce-settings", { method: "GET", query: { fields: ["BUSINESS_INFO"] } })

package/skills/wix-headless-templates/donations/rest/donate.ts

@@ -6,7 +6,7 @@
 // order yourself, never hand-build a checkout URL.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md
 import { wixRequest } from "../../shared/rest/client.js";
 import {
   cartBody,

package/skills/wix-headless-templates/events/seed/seed-events.mjs

@@ -85,7 +85,7 @@ function buildRegistration(ev) {
 // Forms API AFTER the event exists (Create Event ignores form.controls; probed live 2026-09-28). The
 // control lands as a count input (options "0".."N") plus a names list capped at N — the shape the
 // site's form reader (events-core toRsvpForm) reads its max from — and takes effect at once.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/forms/add-control.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/form/add-control.md
 export async function addGuestControl(ctx, eventId, guests) {
   const n = Number(guests);
   if (!Number.isInteger(n) || n < 1) return false;

package/skills/wix-headless-templates/faq/INSTRUCTIONS.md

@@ -296,7 +296,7 @@ without telling the owner.
 
 ## Verification caveats
 
-The FAQ API's reference exists (`https://dev.wix.com/docs/rest/business-management/faq-app/…`) and the
+The FAQ API's reference exists (`https://dev.wix.com/docs/api-reference/business-management/faq-app/…`) and the
 shipped calls follow it: `POST /faq/v2/categories/query`, `POST /faq/v2/question-entries/query`, the
 `RICH_CONTENT` content format and the `SHARE_LINKS` field set. Not confirmed on a live site, and
 guarded in the code:

package/skills/wix-headless-templates/faq/app/wix/faq/faq.ts

@@ -3,8 +3,8 @@
 // rules and mappers live in ./faq-core (shared with the REST twin in templates/faq/rest/); this file
 // is the transport only. Copy as-is; extend by adding functions, not by editing these. The vertical
 // is read-only: authoring stays in the dashboard.
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/category-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/question-entry-v2/query-question-entries.md
 import { category as categoryModule, questionEntry as questionModule } from "@wix/faq";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";

package/skills/wix-headless-templates/faq/project/src/wix/faq/faq.ts

@@ -3,8 +3,8 @@
 // rules and mappers live in ./faq-core (shared with the REST twin in templates/faq/rest/); this file
 // is the transport only. Copy as-is; extend by adding functions, not by editing these. The vertical
 // is read-only: authoring stays in the dashboard.
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/category-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/question-entry-v2/query-question-entries.md
 import { category as categoryModule, questionEntry as questionModule } from "@wix/faq";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";

package/skills/wix-headless-templates/faq/rest/faq.ts

@@ -5,8 +5,8 @@
 // them is not documented — the reference shows an elevated example — so a 403 here means the site's
 // read needs a server-side path, not that the body is wrong (INSTRUCTIONS.md, verification caveats).
 // Porting: keep the paths, keep the bodies, port the core once.
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/category-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/question-entry-v2/query-question-entries.md
 import { wixRequest } from "../../shared/rest/client.js";
 import { imgSrc } from "../../shared/rest/media.js";
 import {

package/skills/wix-headless-templates/faq/seed/SEED.md

@@ -82,7 +82,7 @@ partial re-seed.
 
 ## Verification caveats
 
-The FAQ API's reference pages exist (`dev.wix.com/docs/rest/business-management/faq-app/…`) and
+The FAQ API's reference pages exist (`dev.wix.com/docs/api-reference/business-management/faq-app/…`) and
 every path, verb, and body here follows them; the following were not checked on a live site:
 
 - Whether the create endpoints answer 409 on a duplicate title/question or create a second copy. The

package/skills/wix-headless-templates/faq/seed/read-site.mjs

@@ -3,7 +3,7 @@
 import { runReader } from "../../shared/seed/read-site.mjs";
 
 const FAQ_APP_ID = "14c92d28-031e-7910-c9a8-a670011e062d";
-const D = "https://dev.wix.com/docs/rest/business-management/faq-app/faq";
+const D = "https://dev.wix.com/docs/api-reference/business-management/faq-app";
 
 await runReader({
   vertical: "faq",

package/skills/wix-headless-templates/faq/seed/seed-faq.mjs

@@ -25,7 +25,7 @@ import { readFileSync } from "node:fs";
 
 const API = "https://www.wixapis.com";
 const FAQ_APP_ID = "14c92d28-031e-7910-c9a8-a670011e062d";
-const D = "https://dev.wix.com/docs/rest/business-management/faq-app/faq";
+const D = "https://dev.wix.com/docs/api-reference/business-management/faq-app";
 /** The API's page cap (CursorPaging.limit max 100). */
 const PAGE_LIMIT = 100;
 /** sortOrder step — increments of 10 leave room to insert between items later (the reference's own tip). */
@@ -134,14 +134,14 @@ export async function installFaqApp(ctx) {
 }
 
 // Existing categories, straight from the query (the source of truth for what persisted).
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/category-v2/query-categories.md
 export async function readCategories(ctx) {
   const r = await reqRetryOnce(ctx, "/faq/v2/categories/query", { body: { query: { cursorPaging: { limit: PAGE_LIMIT } } } });
   return (r.categories ?? []).map((c) => ({ id: rawId(c), title: c.title ?? "", sortOrder: typeof c.sortOrder === "number" ? c.sortOrder : null }));
 }
 
 // Every existing question (paged by cursor; PLAIN_TEXT keeps the read light — only the text is compared).
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/query-question-entries.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/question-entry-v2/query-question-entries.md
 export async function readQuestions(ctx) {
   const out = [];
   let cursor = null;
@@ -164,7 +164,7 @@ export async function readQuestions(ctx) {
 //  2. Idempotency — an already-present title (a partial-failure re-run, Wix's sample content) is kept.
 // New categories append after the existing ones: sortOrder = max(existing) + 10, +20, …
 // Body is NESTED: { category: { title, sortOrder } } → { category: { id, … } }.
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/category-v2/create-category.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/category-v2/create-category.md
 export async function ensureCategories(ctx, titles) {
   let existing = await readCategories(ctx);
   const byTitle = () => new Map(existing.map((c) => [norm(c.title), c]));
@@ -196,7 +196,7 @@ export async function ensureCategories(ctx, titles) {
 
 // One question, one call (the SDK exports no bulk create). Body is NESTED: { questionEntry: { … } } →
 // { questionEntry: { id, slug, … } }. `question` and `categoryId` are required; the answer is a oneof.
-// docs: https://dev.wix.com/docs/rest/business-management/faq-app/faq/question-entry-v2/create-question-entry.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/faq-app/question-entry-v2/create-question-entry.md
 export async function createQuestion(ctx, { question, categoryId, sortOrder, labels, answer }, idx) {
   const body = {
     questionEntry: {

package/skills/wix-headless-templates/forms/app/wix/forms/forms.ts

@@ -13,8 +13,8 @@
 // implicit visitor access so a published site can render its own forms. Do NOT add a backend, a
 // connector token, or auth.elevate to make a form load.
 //
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/get-form.md
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/list-forms.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms.md
 // docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
 import { wixFetch } from "../sdk";
 import { imgSrc } from "../media";

package/skills/wix-headless-templates/forms/app/wix/forms/submissions.ts

@@ -13,8 +13,8 @@
 // scope and 403s. The resolved create IS the confirmation — show a thank-you; the entry appears
 // in the owner's dashboard. A site that must LIST what visitors submitted needs `cms` instead.
 //
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/create-submission.md
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/get-media-upload-url.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md?apiView=SDK
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md?apiView=SDK
 // docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 import { submissions as submissionsModule } from "@wix/forms";

package/skills/wix-headless-templates/forms/project/src/wix/forms/forms.ts

@@ -13,8 +13,8 @@
 // implicit visitor access so a published site can render its own forms. Do NOT add a backend, a
 // connector token, or auth.elevate to make a form load.
 //
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/get-form.md
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/list-forms.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms.md
 // docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
 import { wixFetch } from "../sdk";
 import { imgSrc } from "../media";

package/skills/wix-headless-templates/forms/project/src/wix/forms/submissions.ts

@@ -13,8 +13,8 @@
 // scope and 403s. The resolved create IS the confirmation — show a thank-you; the entry appears
 // in the owner's dashboard. A site that must LIST what visitors submitted needs `cms` instead.
 //
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/create-submission.md
-// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/get-media-upload-url.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md?apiView=SDK
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md?apiView=SDK
 // docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 import { submissions as submissionsModule } from "@wix/forms";

package/skills/wix-headless-templates/members/seed/read-site.mjs

@@ -3,7 +3,7 @@
 import { runReader } from "../../shared/seed/read-site.mjs";
 
 const MEMBERS_AREA_APP_ID = "14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9";
-const D = "https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members";
+const D = "https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members";
 
 await runReader({
   vertical: "members",

package/skills/wix-headless-templates/pricing-plans/app/wix/pricing-plans/plan-access.ts

@@ -12,7 +12,7 @@
 //   manual client (React SPA, lib) — the shared seam holds a VISITOR token; pass a call bound to the
 //             member's client instead, e.g. from templates/members' client.ts strategy:
 //             `createClient({ auth: membersAuth, modules: { orders } }).orders.memberListOrders`.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-list-orders.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-orders-service-list-orders.md
 import { orders as ordersModule } from "@wix/pricing-plans";
 import { wixModule } from "../sdk";
 import { hasPlanAccess, memberOrdersQuery, type MemberOrdersQuery } from "./plan-access-core";

package/skills/wix-headless-templates/pricing-plans/project/src/wix/pricing-plans/plan-access.ts

@@ -12,7 +12,7 @@
 //   manual client (React SPA, lib) — the shared seam holds a VISITOR token; pass a call bound to the
 //             member's client instead, e.g. from templates/members' client.ts strategy:
 //             `createClient({ auth: membersAuth, modules: { orders } }).orders.memberListOrders`.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-list-orders.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-orders-service-list-orders.md
 import { orders as ordersModule } from "@wix/pricing-plans";
 import { wixModule } from "../sdk";
 import { hasPlanAccess, memberOrdersQuery, type MemberOrdersQuery } from "./plan-access-core";

package/skills/wix-headless-templates/pricing-plans/rest/plan-access.ts

@@ -4,7 +4,7 @@
 // after the members vertical's rest/auth.ts login (`loggedInHint()` true) — and is refused for a
 // visitor, so callers check the session first (the store does) and never call for a visitor.
 // Porting: keep the path and the query string; the rule is one line in the core.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-list-orders.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-orders-service-list-orders.md
 import { wixRequest } from "../../shared/rest/client.js";
 import { hasPlanAccess, memberOrdersQuery, type MemberOrdersQuery } from "../app/wix/pricing-plans/plan-access-core.js";
 import type { Raw } from "../app/wix/pricing-plans/plans-core.js";

package/skills/wix-headless-templates/restaurants/app/wix/restaurants/menu.ts

@@ -9,7 +9,6 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifier-groups/list-modifier-groups.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifiers/list-modifiers.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-labels/list-labels.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 import {
   menus as menusModule,
   sections as sectionsModule,

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/menu.ts

@@ -9,7 +9,6 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifier-groups/list-modifier-groups.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifiers/list-modifiers.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-labels/list-labels.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 import {
   menus as menusModule,
   sections as sectionsModule,

package/skills/wix-headless-templates/restaurants/rest/menu.ts

@@ -6,7 +6,6 @@
 // port the core once. Entities carry `id` here (the SDK spells it `_id`); the core accepts both.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
 import { wixRequest } from "../../shared/rest/client.js";
 import { imgSrc } from "../../shared/rest/media.js";
 import {

package/skills/wix-headless-templates/shared/rest/client.ts

@@ -14,7 +14,7 @@
 //   server (a Python/PHP/Go port) — the SHOPPER'S SESSION, one token set per shopper. Never one
 //             process-wide token for everyone: that is one shared cart for all visitors.
 //             This is the only part of a port that isn't line-for-line.
-// docs: https://dev.wix.com/docs/go-headless/coding/authentication/visitors.md
+// docs: https://dev.wix.com/docs/go-headless/authentication/visitors/authenticate-visitors-rest.md
 import { WIX_CLIENT_ID } from "./config.js";
 
 export const WIX_API_BASE = "https://www.wixapis.com";

package/skills/wix-headless-templates/shared/seed/site.mjs

@@ -7,7 +7,8 @@ const API = "https://www.wixapis.com";
 // cannot be repriced afterwards. A new site starts in the currency of the account that created
 // it, not the business's. Reads can report the old currency for a few seconds after this returns;
 // that lag is expected and self-resolves.
-// docs: https://dev.wix.com/docs/rest/business-management/site-properties/properties/update-site-properties
+// No reference page documents this PATCH any more (Update Site Properties left the docs). The docs
+// cover the same field only under Update Business Region, a different endpoint and body.
 export async function setSiteCurrency(ctx, currency) {
   if (!/^[A-Z]{3}$/.test(currency)) throw new Error(`currency must be a 3-letter ISO code, got "${currency}"`);
   const res = await fetch(`${API}/site-properties/v4/properties`, {

package/skills/wix-manage/references/google-ads/get-campaign-suggestions.md

@@ -107,4 +107,3 @@ Returns `lowOffer` / `mediumOffer` / `highOffer`, each with `incentiveId`, `awar
 - [Get Keyword Theme Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-keyword-theme-suggestions)
 - [Get Geo Options](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-geo-options)
 - [Get Budget Suggestions](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-budget-suggestions)
-- [Get Incentives](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-incentives)

package/skills/wix-manage/references/google-ads/install-and-create-account.md

@@ -152,4 +152,3 @@ Returns `{}`. Errors with `ACCOUNT_NOT_FOUND` if no account exists.
 - [Account Service](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/introduction)
 - [Create Account](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/create-account)
 - [Get Account For Current Site](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/get-account-for-current-site)
-- [Get Incentives](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-suggestion-v1/get-incentives)

package/skills/wix-manage/references/rich-content/ricos-converter-service.md

@@ -13,7 +13,7 @@ Ricos is Wix's rich content format used across various Wix applications (Blog, S
 - **Convert to Ricos**: Transform HTML, Markdown, or plain text into a Ricos document
 - **Convert from Ricos**: Transform a Ricos document back to HTML, Markdown, or plain text
 
-Learn more about [Rich Content](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-rich-content) and [Ricos document structure](https://dev.wix.com/docs/ricos/getting-started/introduction).
+Learn more about [Rich Content](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-rich-content) and [Ricos document structure](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/document-object).
 
 ## Required API Endpoints
 

package/skills/wix-replatform/resources/rp-mapper/wix-business-solutions-taxonomy.md

@@ -96,9 +96,9 @@ Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart/cart/introduction) |
-| `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the eCommerce Current Cart API](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/introduction) |
-| `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the eCommerce Checkout API](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) |
+| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the Cart API (Cart V2, replaces the eCommerce Cart API)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the Cart API (Cart V2, its Current Cart service)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction?apiView=SDK) |
+| `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the Cart API (Cart V2, replaces the eCommerce Checkout API)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction?apiView=SDK) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
@@ -179,7 +179,7 @@ Primary entities:
 | `ticket-definition` | Ticket type template such as General Admission or VIP | [Event Management introduction](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/introduction) |
 | `ticket` | Purchased ticket with guest and check-in state | [About the Tickets API](https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/tickets/introduction?apiView=SDK) |
 | `event-order` | Ticket purchase and registration order lifecycle | [About the Orders API](https://dev.wix.com/docs/sdk/backend-modules/events/orders/on-order-initiated) |
-| `rsvp` | RSVP response and attendance state for non-ticketed events | [About RSVP API](https://dev.wix.com/docs/sdk/backend-modules/events/rsvp/introduction) |
+| `rsvp` | RSVP response and attendance state for non-ticketed events | [About the RSVP API](https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/introduction?apiView=SDK) |
 | `event-guest` | Unified guest record across ticketed and RSVP events | [About the Event Guests API](https://dev.wix.com/docs/api-reference/business-solutions/events/registration/event-guests/introduction?apiView=SDK) |
 | `events-registration` | Registration layer connecting RSVP, ticketing, and guests | [About Events Registration](https://dev.wix.com/docs/api-reference/business-solutions/events/registration/introduction) |
 
@@ -212,7 +212,7 @@ Primary entities:
 | `reservation` | Reservation lifecycle record for a party at a restaurant | [About the Reservations API](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/wix-restaurants-new/reservations/reservations/introduction) |
 | `restaurant-time-slot` | Availability window for reservation booking | [Reservations API introduction](https://dev.wix.com/docs/rest/business-solutions/restaurants/wix-restaurants-new/reservations/introduction) |
 | `experience` | Special dining experience such as chef's table or tasting menu | [Experiences API](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/wix-restaurants-new/reservations/experiences/introduction) |
-| `restaurant-order-legacy` | Legacy restaurant order model from the original Restaurants Orders app | [About Wix Restaurants Orders](https://dev.wix.com/docs/rest/business-solutions/restaurants/wix-restaurants/orders/introduction) |
+| `restaurant-order-legacy` | Legacy restaurant order model from the original Restaurants Orders app | [Restaurants Online Orders (the legacy Orders docs are removed)](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders) |
 
 Mapper notes:
 - Restaurants spans multiple subdomains: menus, reservations, and in some cases restaurant ordering.

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/docs-survey.json

@@ -273,15 +273,6 @@
       "reason": "Ephemeral purchase-flow state; checkouts are not migratable records.",
       "reviewedOn": "2026-08-11"
     },
-    {
-      "id": "api-reference/business-solutions/e-commerce/purchase-flow/skills",
-      "title": "Skills",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/skills",
-      "group": "Purchase Flow",
-      "verdict": "not-relevant",
-      "reason": "AI-skill documentation page, not a data surface.",
-      "reviewedOn": "2026-08-11"
-    },
     {
       "id": "api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles",
       "title": "Delivery Profiles",

package/skills/wix-vibe-headless/references/blog/INSTRUCTIONS.md

@@ -237,7 +237,7 @@ metrics, members-only posts)? Extend with `wixApiRequest`, but look up the exact
 in the **official Wix API reference** first — never guess. Each helper in `wix-blog.js` links its
 reference page inline.
 - Blog API reference: https://dev.wix.com/docs/api-reference/business-solutions/blog.md
-- Rendering `richContent` (Ricos document): https://dev.wix.com/docs/ricos/api-reference/ricos-document
+- Rendering `richContent` (Ricos document): https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/document-object
 - **Members-only posts** → the **members** vertical: once a member is logged in, the shipped read
   helpers return the gated content with no extra code (member *writes* — comments, likes — are not
   included; add them as an authenticated `wixApiRequest` call).