@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -0,0 +1,57 @@
+# Component Preview (`component.preview.tsx`)
+
+Rules and patterns for the editor-specific entry point that every Editor React
+component ships alongside its main `component.tsx`.
+
+---
+
+## What it is
+
+`component.preview.tsx` is the editor-specific entry point for a component. The
+Wix CLI loads it **instead of** `component.tsx` when rendering the component
+inside the Harmony Editor. It is generated automatically by the scaffold as a
+passthrough that forwards all props unchanged:
+
+```tsx
+const MyComponentPreview = (props: React.ComponentProps<typeof MyComponent>) => (
+  <MyComponent {...props} />
+);
+```
+
+The extension file is also pre-wired to load it — no manual wiring is needed:
+
+```ts
+import componentPreviewUrl from './component.preview.tsx?url';
+
+resources: {
+  client: { componentUrl },
+  editor: { componentUrl: componentPreviewUrl },
+},
+```
+
+---
+
+## `useIsEditMode()`
+
+When you need to distinguish **editor design mode** from **editor preview mode**,
+use `useIsEditMode()` from `@wix/react-component-utils`:
+
+```tsx
+import { useIsEditMode } from '@wix/react-component-utils';
+
+const isEditMode = useIsEditMode();
+// true  → editor is in design mode
+// false → editor is in preview mode
+```
+
+`@wix/react-component-utils` is already a base dependency — no additional install needed.
+
+---
+
+## When to modify it
+
+Modify `component.preview.tsx` whenever the component needs to behave differently
+inside the editor than it does on the live site. The most common case is
+suppressing autoplay so animations don't run while the site owner is designing.
+
+→ See [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) §4 for the autoplay suppression pattern.

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

@@ -19,7 +19,7 @@ There are two kinds of classes, determined by whether the element is a named par
 | Named part | `classNames('profile-card-heading', styles.heading)` | Global string → zeroConfig creates an editor element; module class → applies the component's own CSS |
 | Non-part (layout/structural) | `styles.contentWrapper` | Module class only — invisible to zeroConfig, no spurious editor element created |
 
-**Named parts** get both a global plain string and a module class. The global string is what zeroConfig scans: use `'<component-name>'` for the root and **`'<component-name>-<part-name>'` for every inner part** (kebab-case) — always prefix inner parts with the component name. The module class is what carries the component's structural CSS for that element; it stays short (`styles.heading`) because module classes are hashed and scoped, so they never need the prefix.
+**Named parts** get both a global plain string and a module class. The global string is what zeroConfig scans: use `'<component-name>'` for the root and **`'<component-name>-<part-name>'` for every inner part** (kebab-case) — always prefix inner parts with the component name. The root here is the element elected per [`PARTS.md`](PARTS.md) Step 0, which is the component's own semantic element (`<button>`, `<a>`, `<ul>`) when the component reduces to one. The module class is what carries the component's structural CSS for that element; it stays short (`styles.heading`) because module classes are hashed and scoped, so they never need the prefix.
 
 **Why prefix inner parts:** the global string is a literal class that ends up on the live page, and its design-state variants are derived from it (`<component-name>-<part>--<state>`, e.g. `profile-card-cta--hover`). Those state classes are applied at runtime as global literals, so they must be unique across every component that can share a page — a bare `cta--hover` would collide between two different components. Prefixing with the component name guarantees uniqueness.
 
@@ -27,18 +27,24 @@ There are two kinds of classes, determined by whether the element is a named par
 
 The root also merges the consumer-provided `className` prop via the `classnames` helper.
 
-**Why:** zeroConfig creates one editor element per global class. A global class on a non-part produces a spurious editor element with no meaningful surface.
+**Why:** zeroConfig creates one editor element per global class. A global class on a non-part produces a spurious editor element with no meaningful surface. The root's global class is unavoidable, which is why the root must be an element that deserves it.
 
 ```tsx
 import classNames from 'classnames';
 import styles from './ProfileCard.module.css';
 
 // ✅ Root: global string + module class + consumer className
+// (a <div> here only because this component lays out several sibling parts)
 <div className={classNames(className, 'profile-card', styles.root)} id={id}>
 
   {/* ✅ Named part: prefixed global string + short module class */}
   <h2 className={classNames('profile-card-heading', styles.heading)}>{heading}</h2>
 
+  {/* ✅ Named part: interactive elements always get both classes */}
+  <button type="button" className={classNames('profile-card-cta', styles.cta)}>
+    {ctaLabel}
+  </button>
+
   {/* ✅ Non-part layout wrapper: module class only */}
   <div className={styles.contentWrapper}>
     <span className={classNames('profile-card-label', styles.label)}>{label}</span>
@@ -51,6 +57,25 @@ import styles from './ProfileCard.module.css';
 </CardHeader>
 ```
 
+A component that reduces to one control is the other shape, and it has exactly one
+part — its root ([`PARTS.md`](PARTS.md) Step 0). The text it renders and any decoration
+stay inside that root, on module classes:
+
+```tsx
+// ✅ The <button> is the root: unprefixed global string, no elementProps entry
+<button
+  type="button"
+  id={id}
+  dir={direction}
+  className={classNames('like-button', styles.root, className, styles.fallbackDirection)}
+>
+  {label}
+
+  {/* ✅ Decoration: module class only, out of the a11y tree, not a part */}
+  <span className={styles.burst} aria-hidden="true" />
+</button>
+```
+
 ### Use single-class selectors
 
 Every selector is exactly one class, written as a flat top-level
@@ -465,6 +490,12 @@ slide instead.
 }
 ```
 
+**Media playback is functional, not decorative.** When the component's content
+*is* a playing animation (Lottie/JSON, animated GIF/SVG, canvas/WebGL, video),
+letting it play is allowed — the motion is the content. Such components get a
+play/pause control positioned in CSS. See
+[`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
+
 ### Set `pointer-events: auto` on the root and every interactive element
 
 The root selector and every nested class that the user can click,

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

@@ -31,7 +31,9 @@ nested (`card__row--selected`).
 Put the resting value in the bare class; put only the state override in the
 state selector.
 
-- **Native** — pair the pseudo-class with the `:global` modifier.
+- **Native** — pair the pseudo-class with the `:global` modifier. Every native
+  state needs both selectors in the same rule; do not split the pair across
+  states (for example, pseudo-only `hover` plus global-only `disabled`).
 - **Custom** — the `:global` modifier alone.
 
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
@@ -45,7 +47,8 @@ state class is the **prefixed** global one.
 .cta:hover {
   background: #4f46e5;
 }
-.cta:global(.pricing-card-cta--disabled) {
+.cta:global(.pricing-card-cta--disabled),
+.cta:disabled {
   opacity: 0.5;
 }
 .plan-row:global(.pricing-card-plan-row--selected) {
@@ -124,4 +127,3 @@ Rules:
 Prefer a native state (interactive markup) or a class trigger (per-item data
 such as `row.selected`) whenever one fits — those are the common cases and work
 at any depth. Reach for a prop trigger only for a root-level boolean switch.
-

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

@@ -42,12 +42,29 @@ Use logical CSS properties — never physical `left`/`right`-only layouts. See
 
 ### Root Element Pattern
 
-Apply on main component only:
+Apply on main component only. `dir` and the fallback class go on whatever element is the root — never add a wrapper `<div>` to host them (see [`PARTS.md`](PARTS.md) Step 0).
 
 ```typescript
 <div
+  id={id}
   dir={direction}
   className={classNames(
+    'profile-card',
+    styles.root,
+    className,
+    styles.fallbackDirection,
+  )}
+>
+```
+
+```typescript
+/* Root is the component's own semantic element — same attribute, same classes */
+<button
+  type="button"
+  id={id}
+  dir={direction}
+  className={classNames(
+    'like-button',
     styles.root,
     className,
     styles.fallbackDirection,

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

@@ -1,5 +1,16 @@
 # What Qualifies as a Part
 
+## Step 0 — Elect the root element
+
+The root always becomes the component's editor element: it carries the `'<component-name>'` global class and gets a name and design capabilities either way. So elect a root that deserves them, before enumerating inner parts.
+
+- ✅ **The component reduces to one meaningful element** (a single control, link, media surface, or list) — that element **is** the root. It takes `id`, `dir`, the `fallbackDirection` class, the merged `className`, the `a11y` spread, `'<component-name>'`, and the root CSS rule. All of these are attributes and classes, so they sit on a `<button>` or `<a>` exactly as on a `<div>` — needing them is never a reason to add a wrapper.
+- ✅ **The elected root is the root, not an inner part** — it carries the **unprefixed** `'<component-name>'` class and gets no `elementProps` entry. A single-control component therefore has exactly one named part: its root.
+- ❌ **Wrapper `<div>` holding only root plumbing** — the editor element is then a transparent box and the real element is demoted to a nested part. A root wrapper is justified only when it lays out two or more sibling parts, is the sizing/scroll/clipping container, or hosts a root-level prop-triggered state ([`DESIGN-STATES.md`](DESIGN-STATES.md) §5). Anchoring absolutely positioned decoration is not a justification — `position: relative` works on any element.
+- **Stutter test** — a part class repeating the component's own noun (`confetti-button-button`) means the wrapper took the root's name. Collapse it and promote the real element.
+
+## Inner parts
+
 A **named part** is an element that a site owner would plausibly want to control independently in the editor. Zero config scans global class names and creates an editor element for each one. Each editor element can surface:
 
 - **CSS properties** — styling controls (fill, typography, border, etc.)
@@ -12,7 +23,7 @@ An element deserves its own named part if a site owner would plausibly need to i
 - ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, not a named part.
 - ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
 - ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
-- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs.
+- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, hover/focus states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
 - ❌ **Positional duplicate** — not separate parts. Elements that are semantically identical and differ only in position (e.g. prev/next buttons) are one part; differentiate position with CSS (`:first-of-type` / `:last-of-type`, `data-` attribute, or `:nth-child`).
 - ✅ **Passes all checks** — a named part. Classify as **Semantic** (needs `elementProps`: data, behavior, direction, event handlers) or **Styling-only** (CSS class is sufficient).
 
@@ -22,5 +33,7 @@ Before finalising, verify each proposed part against its parent:
 
 > Would the editor controls generated for this part be a strict subset of its parent's controls?
 
-If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usully better.
+If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usually better.
+
+Then run the same question in reverse, on the root: if the root has exactly one child part and no editor surface of its own, it is a plumbing wrapper — delete it and promote the child per Step 0.
 

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

@@ -9,6 +9,7 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
+- [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
 ## React 18 features are not supported
@@ -22,8 +23,8 @@ React 18 features.
 Understand the component and infer its behavior. Extract what is provided; use reasonable defaults for anything not specified.
 
 1. **Identity** — Component name.
-2. **Structure** — Identify named parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
-3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally.
+2. **Structure** — Elect the root element per [`PARTS.md`](PARTS.md) Step 0, then identify named inner parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
+3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component's primary content is a **playable animation** (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
 4. **States** — For every part, decide which design states it supports (native: `hover`/`focus`/`disabled`/`invalid`; custom: `selected`/`active`/`open`/… ) by applying the heuristic in [`DESIGN-STATES.md`](DESIGN-STATES.md), and record them in the plan. These become the editor's per-element state styling controls.
 
 **Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only and which design states it supports ([`DESIGN-STATES.md`](DESIGN-STATES.md)); build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); give every named inner element an `elementProps` entry and spread it + merge its `className` ([`COMPONENT-API.md`](COMPONENT-API.md)); generate TS + CSS. Infer reasonable defaults where anything is unspecified.
@@ -168,5 +169,5 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 
 **Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
-**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md))
+**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
 

package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md

@@ -31,27 +31,31 @@ This example sorts staff members to balance workload by prioritizing those with
 ```typescript
 import { staffSorting } from "@wix/bookings/service-plugins";
 import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
+import { extendedBookings } from "@wix/bookings";
 
 staffSorting.provideHandlers({
   sortStaffMembers: async (payload) => {
     const { request } = payload;
     const { availableResourceIds, slot } = request;
 
-    // Query recent bookings for each available staff member
-    const elevatedQuery = auth.elevate(bookings.queryBookings);
-    const recentBookings = await elevatedQuery()
-      .eq("resource.id", availableResourceIds)
-      .ge("start.timestamp", new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString())
-      .find();
+    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const elevatedQuery = auth.elevate(extendedBookings.query);
+    const result = await elevatedQuery({
+      filter: {
+        "bookedEntity.item.slot.resource.id": { "$in": availableResourceIds },
+        "startDate": { "$gte": sevenDaysAgo },
+      },
+      cursorPaging: { limit: 100 },
+    });
+    const recentBookings = result.extendedBookings ?? [];
 
     // Count bookings per staff member
     const bookingCounts = new Map<string, number>();
     for (const id of availableResourceIds) {
       bookingCounts.set(id, 0);
     }
-    for (const booking of recentBookings.items) {
-      const resourceId = booking.resource?.id;
+    for (const booking of recentBookings) {
+      const resourceId = booking.booking?.bookedEntity?.slot?.resource?._id;
       if (resourceId && bookingCounts.has(resourceId)) {
         bookingCounts.set(resourceId, (bookingCounts.get(resourceId) ?? 0) + 1);
       }

package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md

@@ -69,6 +69,10 @@ customTriggers.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_DISCOUNTS_TRIGGER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Discount Triggers service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Trigger IDs must match** - The `customTriggerId` in `getEligibleTriggers` must match an `_id` from `listTriggers`

package/skills/wix-app/references/service-plugin/GIFT-CARDS.md

@@ -67,6 +67,10 @@ giftVouchersProvider.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`GIFT_CARDS_PROVIDER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Gift Cards service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **All three handlers required** - You must implement `redeem`, `getBalance`, and `_void`

package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md

@@ -26,7 +26,7 @@ paymentSettings.provideHandlers({
   getPaymentSettings: async ({ request, metadata }) => {
     try {
       // Get the order total
-      const orderTotal = request.order?.totals?.total || 0;
+      const orderTotal = Number(request.order?.priceSummary?.total?.amount) || 0;
 
       // Determine if 3DS is required based on order value
       const require3DS = orderTotal >= HIGH_VALUE_THRESHOLD;
@@ -45,6 +45,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
@@ -83,6 +84,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 

package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md

@@ -53,6 +53,10 @@ shippingRates.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_SHIPPING_RATES` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Shipping Rates service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Price as string** - All price values must be strings, not numbers

package/skills/wix-app/references/service-plugin/TOOLS_PROVIDER.md

@@ -0,0 +1,54 @@
+# Tools Provider Service Plugin Reference
+
+## Overview
+
+The Tools Provider SPI lets your app handle tool invocations from the Wix AI assistant. Implement the `runTool` handler — it receives the tool's `methodName` and a JSON `payload`, runs your business logic, and returns a response the AI assistant uses to answer the user.
+
+This is the execution side of the App Tools feature. The declaration side lives in the `APP_TOOLS` extension. See [APP_TOOLS.md](../APP_TOOLS.md) for the full picture.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `runTool` | https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool?apiView=SDK |
+
+## Example: Routing Tool Calls by methodName
+
+```typescript
+import { toolsProvider } from '@wix/app-tools/service-plugins';
+
+toolsProvider.provideHandlers({
+  runTool: async ({ request, metadata }) => {
+    const { methodName, payload } = request;
+
+    switch (methodName) {
+      case 'get-order-status': {
+        const orderId = payload?.['orderId'];
+        if (typeof orderId !== 'string' || !orderId) {
+          throw new Error('orderId is required');
+        }
+        // fetch order status...
+        return {
+          response: {
+            status: 'shipped',
+            trackingNumber: 'TRACK123'
+          }
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${methodName}`);
+    }
+  }
+});
+```
+
+## Key Implementation Notes
+
+1. **Route on `methodName`** — use a `switch` or map to dispatch to the right handler logic
+2. **Validate inputs defensively** — `requestSchema` is advisory for the AI assistant; Wix does not validate the payload before calling your handler
+3. **Handle all activated tools** — cover every `methodName` with `activated: true` in your `APP_TOOLS` declaration; unhandled names should throw a clear error
+4. **Respond quickly** — the AI assistant is waiting; slow responses degrade the user experience
+5. **Elevate permissions for Wix API calls** — wrap SDK methods with `auth.elevate` from `@wix/essentials`

package/skills/wix-app/references/stores/CATEGORIES.md

@@ -0,0 +1,22 @@
+# Stores — Collections (V1) ↔ Categories (V3)
+
+```typescript
+// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
+// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
+import { products } from '@wix/stores';
+import { categories } from '@wix/categories';
+
+if (v === 'V3_CATALOG') {
+  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
+  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
+  const category = await categories.createCategory(
+    { name: 'Sale' },
+    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
+  );
+  return category;
+}
+const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
+return collection;
+```
+
+V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.

package/skills/wix-app/references/stores/GET_PRODUCT.md

@@ -0,0 +1,99 @@
+# Stores — Get Product
+
+## Get a single product
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);  // returns Product directly
+  return product;
+}
+const { product } = await products.getProduct(id);  // V1 wraps in { product }
+return product;
+```
+
+---
+
+## Read product options and choices (V1 vs V3)
+
+V1 and V3 differ in **both where choices live and what the choice fields are named**. Getting this wrong causes `TS2339` at validate time.
+
+| | V1 | V3 |
+|---|---|---|
+| Options array on product | `product.productOptions` | `product.options` |
+| Option name | `option.name` | `option.name` |
+| Option type | `option.optionType` (`"color"` / `"drop_down"`) | `option.optionRenderType` (`"SWATCH_CHOICES"` / `"TEXT_CHOICES"`) |
+| **Choices array** | `option.choices` ← **directly on the option** | `option.choicesSettings?.choices` ← **nested** |
+| Choice display value | `choice.value` | `choice.name` |
+| Choice color | `choice.value` (hex string) | `choice.colorCode` |
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  for (const option of product.options ?? []) {
+    const choices = option.choicesSettings?.choices ?? [];  // ✅ nested — NOT option.choices / option.optionValues (TS2339)
+    for (const choice of choices) {
+      render(option.name, choice.name, choice.colorCode);   // name = label; colorCode = hex for SWATCH_CHOICES
+    }
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const option of product.productOptions ?? []) {
+    for (const choice of option.choices ?? []) {           // ✅ direct in V1
+      render(option.name, choice.value);                   // value = label or hex string
+    }
+  }
+}
+```
+
+**In a site plugin on a product page**: get `productId` from `widget.getProp('product-id')`, then call the appropriate version's `getProduct` — same pattern as above.
+
+---
+
+## Modifiers (V1 `manageVariants=false` options)
+
+In V3, options that **don't** create variants (V1 `manageVariants=false`) live on `product.modifiers`, not `product.options`. They use the identical `choicesSettings.choices` pattern. Reading only `product.options` silently misses these.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variant-creating options
+  for (const option of product.options ?? []) {
+    for (const choice of option.choicesSettings?.choices ?? []) {
+      render(option.name, choice.name, choice.colorCode);
+    }
+  }
+  // display-only / free-text customizations (formerly manageVariants=false)
+  for (const modifier of product.modifiers ?? []) {
+    for (const choice of modifier.choicesSettings?.choices ?? []) {
+      render(modifier.name, choice.name, choice.colorCode);
+    }
+  }
+}
+```
+
+---
+
+## Variant choices (V1 object map → V3 array)
+
+V1 `variant.choices` was a plain object map `{ "Size": "Small" }`. V3 restructures it as an array — accessing it with a key returns `undefined` silently.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variants are NOT returned by queryProducts — use getProduct or Read-Only Variants API
+  for (const variant of product.variantsInfo?.variants ?? []) {
+    for (const c of variant.choices ?? []) {
+      render(c.optionChoiceNames?.optionName, c.optionChoiceNames?.choiceName);
+    }
+    // ❌ variant.choices['Size'] — always undefined in V3 (object map is gone)
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const variant of product.variants ?? []) {
+    // V1: choices is { [optionName]: value }
+    render(Object.entries(variant.choices ?? {}).map(([k, v]) => `${k}:${v}`).join(', '));
+  }
+}
+```

package/skills/wix-app/references/stores/INVENTORY.md

@@ -0,0 +1,37 @@
+# Stores — Inventory
+
+## Increment stock
+
+```typescript
+import { inventory, inventoryItemsV3 } from '@wix/stores';
+
+if (v === 'V3_CATALOG') {
+  // Per-variant; flat shape.
+  await inventoryItemsV3.bulkIncrementInventoryItems([
+    { inventoryItemId, incrementBy: 5 },
+  ]);
+} else {
+  // Per-product (variant optional).
+  await inventory.incrementInventory([
+    { productId, variantId, incrementBy: 5 },
+  ]);
+}
+```
+
+To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
+
+---
+
+## Query inventory
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const res = await inventoryItemsV3.queryInventoryItems().eq('productId', productId).find();
+  return res.items;
+}
+// V1: filter is a JSON-stringified expression.
+const res = await inventory.queryInventory({
+  query: { filter: JSON.stringify({ productId }) },
+});
+return res.inventoryItems;
+```