@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -0,0 +1,44 @@
+# Entity → SDK Module Map
+
+Data owned by an existing Wix business app is read and written through that app's SDK module — NEVER modeled as a new CMS Data Collection (see the [SDK-First Rule](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms) in `SKILL.md`). A custom collection for such data starts empty and stays disconnected from the real records (e.g., a "refunds dashboard" built on CMS shows an empty state while refunded orders exist in Wix eCommerce).
+
+**Entity → SDK module map** (find the entity the user mentioned, use that package):
+
+| Entity | SDK package |
+| --- | --- |
+| orders / carts / checkout / refund records / fulfillments | `@wix/ecom` — orders live here regardless of vertical |
+| products / inventory / catalog | `@wix/stores` — ⚠️ V1/V3 check, see [STORES_VERSIONING.md](STORES_VERSIONING.md) |
+| payments / refunds / disputes | `@wix/payments` |
+| invoices / payment links / receipts | `@wix/get-paid` |
+| gift cards | `@wix/gift-vouchers` |
+| coupons | `@wix/marketing` |
+| pricing plans / subscriptions | `@wix/pricing-plans` |
+| bookings / services / staff / time slots | `@wix/bookings` |
+| calendar events / schedules | `@wix/calendar` |
+| table reservations | `@wix/table-reservations` |
+| restaurant menus / online orders | `@wix/restaurants` |
+| blog posts | `@wix/blog` |
+| site events / tickets / RSVPs | `@wix/events` |
+| reviews | `@wix/reviews` |
+| comments | `@wix/comments` |
+| groups | `@wix/groups` |
+| online programs | `@wix/online-programs` |
+| donations | `@wix/donations` |
+| portfolio | `@wix/portfolio` |
+| media files | `@wix/media` |
+| contacts / labels / tasks | `@wix/crm` |
+| members | `@wix/members` |
+| inbox conversations | `@wix/inbox` |
+| forms / form submissions | `@wix/forms` |
+| loyalty points / rewards | `@wix/loyalty` |
+| email marketing | `@wix/email-marketing` |
+| notifications | `@wix/notifications` |
+| analytics | `@wix/analytics-data` |
+| automations | `@wix/automations` |
+| SEO tags / redirects | `@wix/seo` |
+| site search | `@wix/search` |
+| secrets | `@wix/secrets` |
+| locations / site properties | `@wix/business-tools` |
+| app instances | `@wix/app-management` |
+
+If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.

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

@@ -5,7 +5,7 @@ Site plugins are custom elements that integrate into predefined **slots** within
 
 ## Scaffold
 
-Use `wix generate --params` with `extensionType: SITE_PLUGIN`. `slotId` is `<componentId>:<slotId>` — the colon-joined widget component ID and slot ID. Run `wix schema generate --type SITE_PLUGIN` to list the available `slotId` values (each `anyOf` entry has the slot's human-readable title). The CLI generates the folder, the plugin `.tsx`, the settings panel `.tsx`, the builder file, the UUID, the logo SVG, and the `src/extensions.ts` registration.
+Use `wix generate --params` with `extensionType: SITE_PLUGIN`. `slotId` is `<componentId>:<slotId>` — the colon-joined widget component ID and slot ID. Run `wix schema generate --type SITE_PLUGIN` to list the available `slotId` values. The CLI generates the folder, the plugin `.tsx`, the settings panel `.tsx`, the builder file, the UUID, the logo SVG, and the `src/extensions.ts` registration.
 
 ## Architecture
 
@@ -43,49 +43,21 @@ Site plugins use native `HTMLElement` custom elements:
 ```typescript
 // my-site-plugin.tsx
 class MyElement extends HTMLElement {
-  static get observedAttributes() {
-    return ['display-name'];
-  }
-
-  constructor() {
-    super();
-  }
-
-  connectedCallback() {
-    this.render();
-  }
-
-  attributeChangedCallback() {
-    this.render();
-  }
+  static get observedAttributes() { return ['display-name']; }
+  connectedCallback() { this.render(); }
+  attributeChangedCallback() { this.render(); }
 
   render() {
     const displayName = this.getAttribute('display-name') || "Your Plugin's Title";
-
-    this.innerHTML = `
-      <div style="font-size: 16px; padding: 16px; border: 1px solid #ccc; border-radius: 8px; margin: 16px;">
-        <h2>${displayName}</h2>
-        <hr />
-        <p>
-          This is a Site Plugin generated by Wix CLI.<br />
-          Edit your element's code to change this text.
-        </p>
-      </div>
-    `;
+    this.innerHTML = `<div style="padding: 16px;"><h2>${displayName}</h2></div>`;
   }
 }
 
 export default MyElement;
 ```
 
-**Key Points:**
+**Key Points** (beyond the structure already listed under [Architecture](#architecture)):
 
-- Extend `HTMLElement` class directly
-- Define `observedAttributes` static getter to list reactive attributes
-- Attributes use **kebab-case** (e.g., `display-name`, `bg-color`)
-- Implement `connectedCallback()` for initial render
-- Implement `attributeChangedCallback()` to re-render when attributes change
-- Use inline styles via template strings
 - Use `this.getAttribute('attribute-name')` to read attribute values
 - Wix handles `define()` for you — do NOT call `customElements.define()` in your code
 
@@ -93,30 +65,22 @@ export default MyElement;
 
 ```typescript
 // my-site-plugin.panel.tsx
-import React, { type FC, useState, useEffect, useCallback } from 'react';
+import { type FC, useState, useEffect, useCallback, type ChangeEvent } from 'react';
 import { widget } from '@wix/editor';
-import {
-  SidePanel,
-  WixDesignSystemProvider,
-  Input,
-  FormField,
-} from '@wix/design-system';
+import { SidePanel, WixDesignSystemProvider, Input, FormField } from '@wix/design-system';
 import '@wix/design-system/styles.global.css';
 
 const Panel: FC = () => {
-  const [displayName, setDisplayName] = useState<string>('');
+  const [displayName, setDisplayName] = useState('');
 
   useEffect(() => {
-    widget.getProp('display-name')
-      .then(displayName => setDisplayName(displayName || "Your Plugin's Title"))
-      .catch(error => console.error('Failed to fetch display-name:', error));
-  }, [setDisplayName]);
+    widget.getProp('display-name').then(v => setDisplayName(v || "Your Plugin's Title"));
+  }, []);
 
-  const handleDisplayNameChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
-    const newDisplayName = event.target.value;
-    setDisplayName(newDisplayName);
-    widget.setProp('display-name', newDisplayName);
-  }, [setDisplayName]);
+  const handleDisplayNameChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+    setDisplayName(e.target.value);
+    widget.setProp('display-name', e.target.value);
+  }, []);
 
   return (
     <WixDesignSystemProvider>
@@ -124,12 +88,7 @@ const Panel: FC = () => {
         <SidePanel.Content noPadding stretchVertically>
           <SidePanel.Field>
             <FormField label="Display Name">
-              <Input
-                type="text"
-                value={displayName}
-                onChange={handleDisplayNameChange}
-                aria-label="Display Name"
-              />
+              <Input type="text" value={displayName} onChange={handleDisplayNameChange} aria-label="Display Name" />
             </FormField>
           </SidePanel.Field>
         </SidePanel.Content>
@@ -141,13 +100,9 @@ const Panel: FC = () => {
 export default Panel;
 ```
 
-**Key Points:**
+**Key Points** (beyond the structure already listed under [Architecture](#architecture)):
 
-- Prop names in `widget.getProp()` and `widget.setProp()` use **kebab-case** (e.g., `"display-name"`)
-- Always update both local state AND widget prop in onChange handlers
-- Widget properties are bound to custom element attributes — changes automatically update the corresponding attribute
-- Wrap content in `WixDesignSystemProvider > SidePanel > SidePanel.Content`
-- Use WDS components from `@wix/design-system`
+- Always update both local state AND widget prop in the same onChange handler
 - Import `@wix/design-system/styles.global.css` for styles
 - Include `aria-label` for accessibility
 
@@ -160,28 +115,17 @@ Site plugin settings panels can use `inputs.selectColor()` and `inputs.selectFon
 Opens the Wix color picker with theme colors, gradients, and more — **NOT** a basic HTML `<input type="color">`.
 
 ```typescript
-import React, { type FC } from 'react';
+import { type FC } from 'react';
 import { inputs } from '@wix/editor';
 import { FormField, Box, FillPreview, SidePanel } from '@wix/design-system';
 
-interface ColorPickerFieldProps {
-  label: string;
-  value: string;
-  onChange: (value: string) => void;
-}
+interface ColorPickerFieldProps { label: string; value: string; onChange: (value: string) => void; }
 
-export const ColorPickerField: FC<ColorPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
+export const ColorPickerField: FC<ColorPickerFieldProps> = ({ label, value, onChange }) => (
   <SidePanel.Field>
     <FormField label={label}>
       <Box width="30px" height="30px">
-        <FillPreview
-          fill={value}
-          onClick={() => inputs.selectColor(value, { onChange: (val) => { if (val) onChange(val); } })}
-        />
+        <FillPreview fill={value} onClick={() => inputs.selectColor(value, { onChange: (val) => val && onChange(val) })} />
       </Box>
     </FormField>
   </SidePanel.Field>
@@ -190,78 +134,21 @@ export const ColorPickerField: FC<ColorPickerFieldProps> = ({
 
 ### FontPickerField
 
-Opens the Wix font picker with font family, size, bold, italic, and other typography features.
+Opens the Wix font picker (family, size, bold, italic). Same shape as `ColorPickerField` above, with a `Button`+`Text` trigger instead of `FillPreview`, calling `inputs.selectFont(value, { onChange })` instead of `selectColor`. Value type: `{ font: string; textDecoration: string }`.
 
-```typescript
-import React, { type FC } from 'react';
-import { inputs } from '@wix/editor';
-import { FormField, Button, Text, SidePanel } from '@wix/design-system';
-
-interface FontValue {
-  font: string;
-  textDecoration: string;
-}
-
-interface FontPickerFieldProps {
-  label: string;
-  value: FontValue;
-  onChange: (value: FontValue) => void;
-}
-
-export const FontPickerField: FC<FontPickerFieldProps> = ({
-  label,
-  value,
-  onChange,
-}) => (
-  <SidePanel.Field>
-    <FormField label={label}>
-      <Button
-        size="small"
-        priority="secondary"
-        onClick={() => inputs.selectFont(value, { onChange: (val) => onChange({ font: val.font, textDecoration: val.textDecoration || "" }) })}
-        fullWidth
-      >
-        <Text size="small" ellipsis>Change Font</Text>
-      </Button>
-    </FormField>
-  </SidePanel.Field>
-);
-```
-
-**Important:**
-- Always use `inputs.selectColor()` from `@wix/editor` with `FillPreview` — do NOT use `<Input type="color">`
-- Always use `inputs.selectFont()` from `@wix/editor` with the callback pattern `inputs.selectFont(value, { onChange })`
-- Import `inputs` from `@wix/editor` (not from `@wix/sdk`)
-
-## Attribute Naming Convention
-
-Site plugins use **kebab-case** consistently for HTML attributes:
-
-| File                              | Convention | Example                            |
-| --------------------------------- | ---------- | ---------------------------------- |
-| `<plugin>.tsx` (getAttribute)     | kebab-case | `this.getAttribute('display-name')` |
-| `<plugin>.tsx` (observedAttributes) | kebab-case | `['display-name', 'bg-color']`     |
-| `<plugin>.panel.tsx` (widget API) | kebab-case | `widget.getProp('display-name')`   |
+**Important:** always go through `inputs` from `@wix/editor` (never `<Input type="color">`, never `@wix/sdk`) with the `{ onChange }` callback pattern shown above.
 
 ## References
 
 | Topic | Reference |
 | --- | --- |
 | Complete Examples | [EXAMPLES.md](site-plugin/EXAMPLES.md) |
-| Slots (App IDs, runtime APIs, design guidelines, multiple placements) | [SLOTS.md](site-plugin/SLOTS.md) — run `wix schema generate --type SITE_PLUGIN` for the authoritative `slotId` enum |
+| Slots (App IDs, runtime APIs, design guidelines, multiple placements) | [SLOTS.md](site-plugin/SLOTS.md) |
 | WDS Components | the `wix-design-system` skill |
 
 ## Available Slots
 
-Site plugins integrate into predefined slots in Wix business solutions. Each slot is identified by:
-
-- **appDefinitionId**: The ID of the Wix app (e.g., Stores, Bookings)
-- **widgetId**: The ID of the page containing the slot
-- **slotId**: The specific slot identifier
-
-Common placement areas include product pages (Wix Stores), checkout and side cart (Wix eCommerce), booking pages (Wix Bookings), service pages, event pages, and blog post pages.
-
-For App Definition IDs, per-slot runtime APIs, design guidelines, and placement constraints, see [SLOTS.md](site-plugin/SLOTS.md). Run `wix schema generate --type SITE_PLUGIN` for the authoritative `slotId` enum.
+Site plugins integrate into predefined slots — product pages (Wix Stores), checkout and side cart (Wix eCommerce), booking pages (Wix Bookings), service pages, event pages, and blog post pages. See [SLOTS.md](site-plugin/SLOTS.md) for the App Definition IDs, per-slot runtime APIs, and design guidelines.
 
 ## Checkout Plugins
 
@@ -269,52 +156,27 @@ If you are building a plugin for the **checkout page**, it may not support autom
 
 ## Examples
 
-For complete examples with all three required files (plugin component, settings panel, extension configuration), see [EXAMPLES.md](site-plugin/EXAMPLES.md).
-
-**Example use cases:**
-
-- **Best Seller Badge** - Customizable badge on product pages with text and color settings
-- **Booking Confirmation** - Custom confirmation message for booking pages
-- **Product Reviews Summary** - Star rating and review count display
-- **Data-Driven Plugin** - Plugin with Wix Data API integration and editor environment handling
+For complete examples with all three required files (plugin component, settings panel, extension configuration) — including a product-page badge, a booking confirmation message, a review-count display, and a Wix Data-driven plugin — see [EXAMPLES.md](site-plugin/EXAMPLES.md).
 
 ## Best Practices
 
 ### Implementation Guidelines
 
-- **Use inline styles** - CSS imports are not supported in custom elements
-- **Handle editor environment** - Show placeholders when in editor mode for data-dependent plugins
-- **Do not call `define()`** - Wix handles `customElements.define()` for you automatically
-- **Validate all input** - Check required props are present
-- **Follow naming conventions** - kebab-case for all attributes and widget API
-- **Keep plugins focused** - Each plugin should do one thing well
-- **Test in multiple slots** - If supporting multiple placements, test each one
-- **Support both Stores versions** - Include placements for both old and new Wix Stores product pages for maximum compatibility
+- **Handle the editor environment** - show placeholders when in editor mode for data-dependent plugins (see [Editor Sandboxing](#editor-sandboxing) below)
+- **Support both Stores versions** - include placements for both old and new Wix Stores product pages for maximum compatibility
 
 ### Editor Sandboxing
 
-Site plugins are sandboxed when rendered in the editor. This means they're treated as if they come from a different domain, which impacts access to browser storage APIs.
-
-**Restricted APIs in the editor:**
-- `localStorage` and `sessionStorage` (Web Storage API)
-- `document.cookie` (Cookie Store API)
-- IndexedDB API
-- Cache API
+Site plugins are sandboxed when rendered in the editor — treated as if from a different domain, which blocks `localStorage`/`sessionStorage`, `document.cookie`, IndexedDB, and the Cache API.
 
-**How to handle sandboxing:**
-
-Use the `viewMode()` function from `@wix/site-window` to check the current mode before accessing restricted APIs:
+Check the mode with `viewMode()` from `@wix/site-window` before touching any of those. That package isn't part of the CLI's default scaffolded `package.json` — install it first (`npm install @wix/site-window`), or the build fails with `Rollup failed to resolve import "@wix/site-window"`:
 
 ```typescript
 import { window as wixWindow } from '@wix/site-window';
 
-const viewMode = await wixWindow.viewMode();
-
-if (viewMode === 'Site') {
+if ((await wixWindow.viewMode()) === 'Site') {
   const item = localStorage.getItem('myKey');
-} else {
-  // Mock storage or modify API usage for editor mode
-}
+} // else: mock storage or skip, in editor mode
 ```
 
 ### Using Wix SDK Modules in Site Plugins
@@ -322,33 +184,23 @@ if (viewMode === 'Site') {
 Site plugins can import and use Wix SDK modules directly — you do NOT need `createClient()`. The Wix runtime provides the client context automatically.
 
 ```typescript
-// ✅ CORRECT — Import SDK modules directly
+// ✅ CORRECT — import directly, no createClient needed
 import { items } from "@wix/data";
-import { currentCartV2 } from "@wix/ecom";
-import { products } from "@wix/stores";
 
 class MyPlugin extends HTMLElement {
   async loadData() {
-    // Call SDK methods directly — no createClient needed
     const result = await items.query("MyCollection").find();
-    const { cart } = await currentCartV2.getCurrentCart();
-    const productList = await products.queryProducts().limit(10).find();
   }
 }
 ```
 
-```typescript
-// ❌ WRONG — Do NOT use createClient in site plugins
-import { createClient } from "@wix/sdk";
-const wixClient = createClient({ modules: { items, products } });
-await wixClient.items.query(...); // Wrong — API surface differs through client
-```
+The same applies to any other Wix SDK module (`@wix/ecom`, `@wix/stores`, etc. — see the table below for three specific calls). Do **not** wrap them in `createClient({ modules: {...} })` from `@wix/sdk` — that API surface differs from the direct-import one shown above, and site plugins don't need it.
 
 ### Identity of SDK Calls in Site Plugins
 
 A plugin runs as the **site visitor or member**, never as the app — see [Identity and Elevation Requirement](../SKILL.md#identity-and-elevation-requirement) before routing any SDK call out to a backend endpoint.
 
-The three calls above are correct exactly as written, and each for a different reason:
+Each of these three calls is correct to call directly, exactly as written, and each for a different reason:
 
 | Call | Why it works directly |
 | --- | --- |
@@ -356,9 +208,3 @@ The three calls above are correct exactly as written, and each for a different r
 | `currentCartV2.getCurrentCart()` | Resolves the cart from the caller's session. Elevating it would return the app's cart, not the visitor's |
 | `products.queryProducts()` | Catalog base fields are public. `MERCHANT_DATA` and non-visible products are withheld unless the app holds `SCOPE.STORES.PRODUCT_READ_ADMIN` — don't request them from a plugin |
 
-### Performance Considerations
-
-- Keep bundle size small - plugins load on user-facing pages
-- Avoid heavy computations on initial render
-- Lazy load data when possible
-- Use efficient re-rendering patterns

package/skills/wix-app/references/app-tools/TOOLS.md

@@ -25,6 +25,7 @@ export default extensions.appTools({
   tools: [
     {
       methodName: 'get-order-status',
+      displayName: 'Get Order Status',
       description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
       requestSchema: {
         type: 'object',
@@ -52,9 +53,10 @@ export default extensions.appTools({
 | --- | --- | --- | --- |
 | `methodName` | `string` | Yes | Unique word identifying the tool. Used to route calls in the service plugin handler. 1–30 characters. |
 | `description` | `string` | Yes | Natural-language description the AI assistant uses to decide when to invoke this tool. Write it like a prompt: state what the tool does, list the user intents or trigger phrases that should activate it, and describe what it returns. A narrow one-liner reduces relevance matching — prefer 2–4 sentences covering intent, triggers, and output. 10–1000 characters. |
+| `displayName` | `string` | No | Human-readable name for the tool, shown in AI agent UIs. 2–50 characters. The CLI's generated stub always fills this in — keep it when you replace the stub tool. |
 | `requestSchema` | `Record<string, any>` | No | JSON Schema describing the tool's request payload. The AI assistant uses this for context — it is NOT validated by Wix at call time. |
 | `responseSchema` | `Record<string, any>` | No | JSON Schema describing the tool's response payload. |
-| `activated` | `boolean` | Yes | Only tools with `activated: true` are called by the AI assistant. |
+| `activated` | `boolean` | No | Only tools with `activated: true` are called by the AI assistant. **Defaults to `false` if omitted** — there's no build-time or generate-time error for leaving it out, so a forgotten `activated` silently produces a tool the assistant will never call. Always set it explicitly. |
 
 ## Important Constraints
 

package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md

@@ -32,3 +32,24 @@ Wrap each picker in the standard `<SidePanel.Field><FormField label={label}>…<
 </Button>
 ```
 
+## Date & Time Fields
+
+Use WDS `DatePicker` and `TimeInput` directly (no `@wix/editor` picker dialog involved) — but their `onChange` shapes differ, verified against the installed package's own types:
+
+| Field | Value type | `onChange` signature |
+|---|---|---|
+| `DatePicker` | `Date` | `(date: Date) => void` — receives the date directly |
+| `TimeInput` | `Date \| null` | `({ date }: { date: Date \| null }) => void` — receives a **destructured object**, not the date directly |
+
+```typescript
+import { FormField, DatePicker, TimeInput } from '@wix/design-system';
+
+<FormField label="Target date">
+  <DatePicker value={targetDate} onChange={(date) => onDateChange(date)} />
+</FormField>
+
+<FormField label="Target time">
+  <TimeInput value={targetTime} onChange={({ date }) => onTimeChange(date)} />
+</FormField>
+```
+

package/skills/wix-app/references/dashboard-page/DATA_SOURCES.md

@@ -0,0 +1,182 @@
+# Finding the real SDK shape behind a dashboard page
+
+> **Scope.** [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) gives you the page. This file is the other half:
+> locating the method and the *field names* for the data it lists. Read it before Step 3's MCP
+> discovery — the installed package answers most of it faster and more accurately than a doc search,
+> because it is the version your code will compile against.
+
+## Where the types actually live
+
+A Wix vertical package such as `@wix/ecom` is a thin re-export barrel. `build/es/index.d.mts` is a
+list of namespaces (`orders`, `orderTransactions`, `currentCart`, …), each re-exported from its own
+generated package:
+
+```
+node_modules/@wix/ecom/build/es/index.d.mts          # namespace list only, ~90 lines
+node_modules/@wix/auto_sdk_ecom_orders/build/es/
+  index.d.mts                                        # the callable functions
+  index.typings.d.mts                                # request/response types
+  ecom-v1-order-orders.universal-<hash>.d.mts        # the domain entities
+```
+
+Three consequences worth knowing before you start grepping:
+
+1. **The directory name is not the namespace name.** Namespaces are camelCase, package directories
+   are kebab-case — `extendedBookings` lives in `auto_sdk_bookings_extended-bookings`, not
+   `auto_sdk_bookings_extendedBookings`. Don't derive one from the other; list them:
+   `ls node_modules/@wix | grep <vertical>`.
+2. **The entity is not always in `index.typings.d.mts`.** `Order`, `Refund`, `Service` live in the
+   hashed `*.universal-*.d.mts` when the package has one. The hash changes between versions, so glob
+   for it, never hard-code it, and fall back to `index.typings.d.mts` when no universal file exists.
+3. **Never `cat` *or plain-`grep`* the barrel's export block.** These files end with a single
+   several-hundred-KB `export { … as a, … as b }` line, so `grep -n "queryServices" index.d.mts`
+   prints that whole line. Anchor to the declarations instead —
+   `grep -oE "^declare (const|function) [a-zA-Z]+"` — or pipe any barrel grep through `cut -c1-200`.
+
+## Confirming a method
+
+```bash
+E=node_modules/@wix/auto_sdk_ecom_order-transactions/build/es
+grep -oE "^declare function [a-zA-Z]+" $E/index.d.mts
+```
+
+Prefer this to recall: `listTransactionsForMultipleOrders(orderIds: string[])` and
+`listTransactionsForSingleOrder` differ by exactly the shape a collection page needs, and only one
+of them avoids an N+1 across the visible page.
+
+## Confirming a field — the part that ships bugs
+
+Once you have the entity, read the declaration for **every field you map into a column**, not just
+the uncertain ones. Two failure modes recur:
+
+**Deprecated fields still compile.** On `RegularPaymentDetails`, `paymentMethod` carries
+`@deprecated Use paymentMethodName.buyerLanguageName instead` — the deprecated one is a bare code,
+the replacement is the localised name a person expects to read. Grep before you map:
+
+```bash
+grep -B4 "paymentMethod?:" $E/index.typings.d.mts   # shows the @deprecated banner above it
+```
+
+A column bound to a deprecated field renders something plausible and wrong, which is the hardest
+kind of defect to catch in review.
+
+**Aggregates hide one level down.** Money on a refund is not on the refund — it is
+`refund.summary.refunded.amount` (`AggregatedRefundSummary`, with `pendingRefund`, `failedRefundAmount`
+and `requestedRefund` beside it), while per-transaction status is
+`refund.transactions[].refundStatus`. Summing the wrong one silently under-reports.
+
+**A generic-sounding field is not the related entity.** Treat `.title`, `.name` and `.summary` as
+unverified until you read the declaration: an `Extended*` / `*WithDetails` shape exists precisely to
+attach the real related entity, and a summary field on the base item is not a substitute. A column
+must show what its header promises.
+
+**A mapper must cover every shape the response returns.** Responses often carry a oneof — Bookings'
+`bookedEntity` is `slot` for an appointment, `schedule` for a class — and a mapper reading one
+variant renders blank cells for the other while passing `tsc`.
+
+## Joining two sources for one row
+
+A collection page usually needs one query plus one batch lookup, never a lookup per row:
+
+```ts
+const { orders: found } = await orders.searchOrders({ filter, sort, cursorPaging: { limit, cursor } });
+const ids = found.map((o) => o._id).filter((id): id is string => Boolean(id));
+const { orderTransactions: txns } = await orderTransactions.listTransactionsForMultipleOrders(ids);
+const byId = new Map(txns.map((t) => [t.orderId, t]));
+```
+
+Build the `Map` once and index it in the row mapper. Guard the empty case before the second call —
+a batch endpoint given `[]` is a wasted round trip at best.
+
+## Filter syntax
+
+`searchOrders` takes a `CursorSearch`: `{ cursorPaging, filter, sort }`, where `filter` is a
+Mongo-shaped `Record<string, any>` — `{ paymentStatus: { $in: [...] } }`,
+`{ _createdDate: { $gte, $lte } }`, `{ number: { $startsWith } }`. Enum values come from the
+declaration, not from memory: order payment status is `FULLY_REFUNDED` / `PARTIALLY_REFUNDED` /
+`PAID` / `NOT_PAID` / `PENDING` / `PARTIALLY_PAID` / `PENDING_MERCHANT` / `CANCELED` / `DECLINED` /
+`UNSPECIFIED`.
+
+## The SDK is not the REST API
+
+Docs search returns REST pages, and a dashboard page calls the **SDK**. Append `?apiView=SDK` to the
+URL of whatever page you landed on and read that view — it answers two of the four differences
+before you write a line.
+
+**1 and 2 — namespace and id naming. The SDK view states both.** It prints the package and namespace
+outright (`SDK Package: @wix/members`, `SDK Namespace: customFields`), and uses `_id` in its own
+parameter list. Infer either from the REST page and you get them wrong: REST paths say `services/v2`,
+so `servicesV2` looks right, and the SDK exports `services`; REST responses show `"id"`, and the SDK
+type declares `_id` — same for `_createdDate` / `_updatedDate`. Offline, the barrel is the fallback
+for the namespace list:
+
+```bash
+grep -oE "as [a-zA-Z_]+" node_modules/@wix/<pkg>/build/es/index.d.mts | sed 's/as //' | sort -u
+```
+
+The next two are codegen artifacts that no docs page mentions — read them off the declaration.
+
+**3. Don't derive types from `ReturnType`.** Most SDK functions are overloaded — a direct call
+and an `httpClient` form — so `Awaited<ReturnType<typeof ns.method>>['items'][number]` resolves
+against the wrong overload and fails. Import the entity type the package exports instead:
+
+```ts
+type Row = <namespace>.<Entity>;   // e.g. extendedBookings.ExtendedBooking — not ReturnType<typeof …>
+```
+
+**4. Paging metadata carries no `hasNext`.** `PagingMetadataV2` is `count`, `offset`, `total`,
+`tooManyToCount`, `cursors` — nothing else, in every generated package. Whether another page exists
+is knowable only from `pagingMetadata.cursors.next`. What the collection wants you to *return* is a
+separate question — see [TABLE_STATE.md](TABLE_STATE.md#query-and-result-shapes).
+
+## Two things to settle before you write the page
+
+**Is the package even installed?** A vertical's SDK is not a default dependency. `@wix/bookings`,
+`@wix/ecom` and the rest have to be present before the import resolves:
+
+```bash
+node -e "const p=require('./package.json');console.log(!!({...p.dependencies,...p.devDependencies})['@wix/<pkg>'])"
+npm install @wix/<pkg>     # if false
+```
+
+**Does the app hold the scope?** This is the one that produces a page which builds, mounts, renders
+its shell, and shows nothing — the hardest failure to read, because an empty table looks like empty
+data. Reads of a vertical's data need that vertical's permission scope, granted in **Dev Center →
+Permissions**; it cannot be declared in the repo, and the app's install consent screen names what it
+actually has.
+
+**Don't guess the scope name — the method's own docs page prints it.** In SDK view every method
+carries `Method Permissions` and `Method Permissions Scopes IDs`, for example
+`Manage Members: SCOPE.DC-MEMBERS.MANAGE-MEMBERS`. Look it up for the exact method you are calling,
+assume it is missing on a fresh app, and report it under
+[Manual Steps Required](../../SKILL.md#-manual-steps-required) by name. Wiring `errorState` on the
+table (the draft template does) is what turns this from silent skeletons into a message you can read.
+
+## A second vertical is a second scope
+
+The two checks above are easy to run once, at Step 3, for the vertical the page is obviously about —
+and then to skip for the *next* one, because by then you are deep in Step 4b adding a detail column
+or resolving a search term. That second package needs the same two things, and it fails differently:
+the page already worked, so the regression looks like something you broke in the UI.
+
+A measured run added `@wix/crm` mid-implementation to resolve a client-name search. The app held
+Bookings scopes and not `SCOPE.DC-CONTACTS.READ-CONTACTS`, the contacts call answered 403, and
+because the search awaited it unconditionally, a page that had been loading fine stopped loading at
+all.
+
+**Run the package-and-scope check for every `@wix/*` import you add, whenever you add it** — and
+then decide what its failure should cost:
+
+- **Primary source** — the rows themselves. Its failure is the page's failure; `errorState` reports it.
+- **Secondary source** — an enrichment lookup, a filter's option list, a term resolved to ids. Its
+  failure must cost only that feature. Wrap the call, fall back to the empty result, and say so in
+  the UI (`TableTopNotification` is the patterns component for it) rather than degrading silently.
+
+Ask which one you are adding before you write the `await`. An unwrapped secondary call is a page
+whose availability is the *intersection* of every scope it touches.
+
+## Querying and paging
+
+Filter field paths, WQL's one-operator-per-field rule, and the two cursor-paging traps are in
+[QUERY_AND_PAGING.md](QUERY_AND_PAGING.md). Read it before writing `fetchData` — every rule there
+was a shipped bug first.