@wix/agent-skills 1.18.2 → 1.19.1

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

@@ -24,7 +24,8 @@ roles intact.
 
 ## Workflow
 
-1. **Scaffold only when creating.** If the component folder does not exist, run:
+1. **Scaffold only when creating.** If the component folder does not exist, run
+   inside the Wix app project (the folder with `wix.config.json`):
 
    ```bash
    npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
@@ -37,7 +38,7 @@ roles intact.
    accessibility-review dependencies are installed:
 
    ```bash
-   node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y'];const missing=ps.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(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y; fi; }
+   node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y','jsdom','axe-core'];const missing=ps.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(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-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; fi; }
    ```
 
 3. **Plan the contract and structure.** Identify props, semantic root, named
@@ -47,10 +48,16 @@ roles intact.
    the props file, logic in TSX, styles in the CSS Module. Do not edit
    `*.generated.ts`.
 
-5. **Run the accessibility review.** Follow
-   [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md): run scanners,
-   triage output, complete the manual checklist, fix issues, rerun on changed
-   JSX.
+5. **Run the accessibility review.** Once the JSX is complete, run from the
+   same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
+
+   ```bash
+   node <SKILL_ROOT>/scripts/scan-a11y-review.cjs src/extensions/site/components/<component-name>
+   ```
+
+   Then follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
+   fix confirmed findings, rerun after each fix pass (at most two), and report
+   what remains.
 
 6. **Configure the editor extension when required.** For a new component or a
    requested sizing, installation, or manifest change, apply
@@ -121,7 +128,9 @@ extension configuration, and supporting files.
 - Explicit foreground colors need a known contrasting background; transparent
   roots inherit from the host.
 - Baseline Widely Available CSS/DOM only, or supported fallbacks.
-- Route ARIA through `a11y`; no one-off ARIA props.
+- Accessibility per part, per [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
+  read only `a11y.ariaLabel`, and only for a control without a visible name;
+  never spread the `a11y` object or add one-off ARIA props.
 - Named parts: global class, module class, and `elementProps` (root uses
   top-level props).
 - Native design states: pair selectors with injected modifiers; keep non-input

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

@@ -1,19 +1,24 @@
 
 # Extension Registration
 
-`src/extensions.ts` is the single entry point that tells the build system which extensions exist. Without a `.use()` call for an extension, it does not load.
+`src/extensions.ts` is the single entry point that tells the build system which extensions exist. Without a `.use()` call for an extension, it does not load. HTTP endpoints are file-based routes and do not use this registration mechanism.
 
 ## Registration is automatic via the CLI
 
-For every CLI-supported extension type, `wix generate --params` updates `src/extensions.ts` for you — you do NOT need to write the import or the `.use()` call by hand. Verify the file was updated after each `wix generate` invocation.
+For every CLI-supported extension type, `wix generate --params` updates `src/extensions.ts` for you — you do NOT need to write the import or the `.use()` call by hand. Verify the file was updated after each `wix generate` invocation. The one exception is `HTTP_ENDPOINT`: it is file-based, `wix generate` does not touch `src/extensions.ts` for it, and an unchanged file after generating an endpoint is expected (see below).
 
-## Extension types that require manual registration
+## HTTP endpoints: no registration
 
-| Type | Why manual |
-| --- | --- |
-| **Backend API** | Astro endpoints under `src/pages/api/` are auto-discovered by the runtime. They do not need to be added to `src/extensions.ts`. |
+`wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}'`
+creates the endpoint file without changing `src/extensions.ts`:
 
-Every other extension type is wired up automatically by the CLI.
+| Project | Discovery directory | Example route |
+| --- | --- | --- |
+| `@wix/custom-extensions` (default `apiDir: "endpoints"`) | `src/endpoints/` | `hello.ts` → `/hello` |
+| `@wix/astro` | `src/pages/api/` | `hello.ts` → `/api/hello` |
+
+Leave `app()` unchanged. Do not add endpoint imports, `.use()` calls, or IDs.
+See [BACKEND_API.md](BACKEND_API.md) for supported versions and frontend URLs.
 
 ## Manual recovery (when the CLI output drifts)
 
@@ -21,7 +26,6 @@ Edit `src/extensions.ts` directly only when:
 
 - The CLI failed mid-run and left the file out of sync
 - A user hand-edited the file and broke the chain
-- You're adding a Backend API helper (uncommon)
 
 Each extension file is a default export from `<folder>/<folder>.extension.ts`. In `src/extensions.ts`, import it as a default import using the camelCase of the folder name, then chain `.use(...)`:
 

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

@@ -2,174 +2,96 @@
 
 ## Prerequisites
 
-Lookups here are direct file reads — no script. Resolve the installed package root once per session and reuse it:
+Resolve the package root once per session and reuse it — a bare `require.resolve` throws under Yarn PnP:
 
 ```bash
-node -e "
-const fs = require('fs'), path = require('path');
-function tryEnablePnp() {
-  let dir = process.cwd();
-  for (;;) {
-    const pnp = path.join(dir, '.pnp.cjs');
-    if (fs.existsSync(pnp)) { try { require(pnp).setup(); } catch {} return; }
-    const parent = path.dirname(dir);
-    if (parent === dir) return;
-    dir = parent;
-  }
-}
-tryEnablePnp();
-try {
-  console.log(path.dirname(require.resolve('@wix/patterns/package.json', { paths: [process.cwd()] })));
-} catch {
-  let dir = process.cwd();
-  for (;;) {
-    const candidate = path.join(dir, 'node_modules', '@wix', 'patterns');
-    if (fs.existsSync(path.join(candidate, 'package.json'))) { console.log(candidate); process.exit(0); }
-    const parent = path.dirname(dir);
-    if (parent === dir) { console.error('@wix/patterns not found'); process.exit(1); }
-    dir = parent;
-  }
-}
-"
+node <this-skill-dir>/scripts/pkg-root.cjs @wix/patterns
 ```
 
-A bare `require.resolve` without the PnP-activation step throws in a Yarn Berry project even when installed — run the whole snippet, not a shortened version.
+Then check the install, two ways: `ls <pkgRoot>/dist/dts-bundle/index.json`, and — the one that matters — look for a **`Collection Toolkit`** key once step 1 has the docs index. The guides are *entries inside* that index rather than a directory, so no missing file reveals their absence.
 
-Then confirm the installed version actually ships the bundle index:
+**If either fails, stop and upgrade `@wix/patterns`.** "Which component serves this need" now lives in the package, so proceeding means guessing names; do not hunt elsewhere in `node_modules` for a substitute. Everything below degrades by version rather than breaking, so probe rather than version-check.
 
-```bash
-ls <pkgRoot>/dist/dts-bundle/index.json
-```
+**Patterns API facts come from three published trees only:** `dist/docs/` (pages), `dist/dts-bundle/` (types), `dist/examples/` (worked calls). Never take a component, prop or type from `src/`, `dist/esm/` or `dist/cjs/`, or a deep path a bundle mentions — internals change without notice. `dist/types/` is one narrow exception, used only where step 5 says: `package.json` points `types` at it, so it is what `tsc` enforces. Within those trees, `grep`/`sed` for one declaration usually beats a whole-file read.
 
-**If it's missing, stop — do not look elsewhere for types or docs.** The installed `@wix/patterns` predates the index (ships from **1.458.0**); upgrade and re-run the check. Prefer **1.465.0**+ — the lookups below assume it (`OffsetQuery`, `useEntityPage`'s create route, `withDashboard.md`, a deprecation `status` in `dist/docs/index.json`, page-relative router paths). A missing *file* isn't the same as a name not being covered (see below).
+## The Discovery Chain
 
-**Never inspect `node_modules` by hand** — no `ls`, `find`, or `cat` of an arbitrary path, not even `dist/dts-bundle/` or `dist/docs/`. Every lookup below names the exact file to `Read` — go straight to it.
+### 1 — The index
 
-## Library Architecture
+**Probe `<pkgRoot>/dist/docs/index.json`; do not read it whole.** At ~80 KB a `Read` truncates part-way and reports nothing, so the tail goes silently missing. Pull what you need with one `grep`/`python3` call, resolving every symbol you plan to write in it.
 
-### Composition Hierarchy
+Start here rather than the bundle index: it carries every documented name *and* the guides.
 
-```
-Provider                     <- WixPatternsProvider or WixPatternsBMProvider
-  +-- Page                   <- CollectionPage, EntityPage, or SettingsPage
-       +-- Collection        <- Table, Grid, TableGridSwitch, etc.
-            +-- Features     <- filters, actions, sorting, drag-and-drop, etc.
-```
+- **Read each entry's `summary` before opening anything.** It is that page's opening paragraph, so for most questions the index *is* the answer and step 4 becomes no read.
+- **Resolve against the keys *and* each entry's `symbols` aliases.** The index is keyed by Storybook title: `ExportButton` lives under `ExportTo`, `CollectionToolbarFilters` under `ToolbarFilters`. Matching is exact — scan for something close before concluding a name isn't covered.
+- **`status: "deprecated"`** means use what `statusMessage` names. A deprecated component still renders, so nothing else stops you.
 
-### The Collection Triad
+**Not in the docs index? Check `dist/dts-bundle/index.json` before concluding it does not exist.** It curates names with no page of their own — hooks, prop and query types, names re-exported from another package — and carries `importPath` and `file`, so step 4 still applies with no page to read.
 
-Each collection type follows the same Component + State + Hook pattern:
+**For that whole namespace cheaply, `Read <pkgRoot>/dist/dts-bundle/index.txt`** — ~9 KB, one read, every curated name with `kind`, `importPath` and file. From 1.469.0 it adds `bytes`, `props` (`5/63` — what the file declares against what the symbol has) and `stubs`: step 5's triage for every symbol at once, with the columns named in its header. Drop to the `.json` for `readWith`, `readWithBytes` and status prose.
 
-| Component | State Type | Hook |
-| --- | --- | --- |
-| `Table` | `TableState` | `useTableCollection()` |
-| `Grid` | `GridState` | `useGridCollection()` |
-| `TableGridSwitch` | `TableGridSwitchState` | `useTableGridSwitchCollection()` |
-| `TableFolders` | `TableFoldersState` | `useTableFolders()` |
-| `GridFolders` | `GridFoldersState` | `useGridFolders()` |
+### 2 — Composition, once per session
 
-Common types only; `dist/dts-bundle/index.json` has the authoritative set. Create state with the hook -> pass it to the component's `state` prop -> wrap in a page component.
+`Read <pkgRoot>/dist/docs/Composition and Providers.md` before writing any patterns JSX: which provider, the four nesting layers, the collection triad, and why the provider must be a parent component rather than a sibling — the mistake that throws at runtime while the JSX looks right.
 
-### Choosing the Right Provider
+### 3 — Which component serves this need
 
-| Provider | When to Use |
+| Building | Guide |
 | --- | --- |
-| `WixPatternsProvider` | **Default — start here.** Auto-detects the environment (BM, Essentials, Giza). |
-| `WixPatternsBMProvider` / `WixPatternsGizaProvider` | Optional alternatives for Yoshi BM Flow (Business Manager / Giza). |
-| `WixPatternsEssentialsProvider` | Yoshi Fullstack. |
-| `WixPatternsBaseProvider` | App does **not** run under Giza/WixEssentials and you inject services (i18n, sentry) yourself. |
-
-**Confirm the import path in the provider's own bundle** — not all share a subpath (`WixPatternsEssentialsProvider`, `WixPatternsBaseProvider` live under `@wix/patterns/essentials`).
-
-### Keep Provider and Page Separate
-
-The provider **must** be a parent of the page content: hooks like `useTableCollection` need its context above them in the tree.
-
-**Wrong:** calling `useTableCollection` in the component that renders `WixPatternsProvider` — the hook runs before the provider exists, so it throws at runtime even though the JSX looks right.
-
-**Correct — provider in root, page in a separate file:**
-```tsx
-// App.tsx
-import { WixPatternsProvider } from '@wix/patterns/provider';
-
-function App() {
-  return (
-    <WixPatternsProvider>
-      <MyCollectionPage />
-    </WixPatternsProvider>
-  );
-}
-
-// MyCollectionPage.tsx
-import { Table, useTableCollection, OffsetQuery } from '@wix/patterns';
-import { CollectionPage } from '@wix/patterns/page';
-
-function MyCollectionPage() {
-  // works — the provider context exists above this component
-  const state = useTableCollection({
-    queryName: 'my-items',
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    fetchData: async (query: OffsetQuery) => ({ items: [], total: 0 }),
-    filters: {},
-  });
-  return (
-    <CollectionPage>
-      <Table state={state} columns={[{ title: 'Name', render: (item) => item.name }]} />
-    </CollectionPage>
-  );
-}
-```
+| Anything collection-shaped — tables, filters, search, aggregates, row and bulk actions, empty states | `dist/docs/Collection Toolkit.md` |
+| The path from a listed row to one record, and its form | `dist/docs/Collection to Entity Flow.md` |
 
-Keep the provider (and router, if any) in the app's root component and each page in its own file.
+Each guide's index entry carries `relatedComponents`; every name in it resolves, because `@wix/patterns` fails its own build otherwise. Prefer one of those over a name you recall.
 
-For **multiple pages**, use the `@wix/patterns` routing solution (`PatternsReactRouter`, `PatternsReactRoute`, `usePatternsNavigate`) rather than a separate router. Read `PatternsReactRouter.md` and `withDashboard.md` for setup — the router reads page location from the dashboard context `withDashboard` renders, so it needs that wrapper above it with a `location` prop, and throws at render time without them. (it ships from **1.465.0**; no entry in `dist/docs/index.json` means an older install — use `PatternsReactRouter.md`'s **Requirements**.)
+### 4 — Read only what answers your question, then stop
 
-## How to Look Things Up
+| Your question | Read | Path |
+| --- | --- | --- |
+| What is it, and how does it wire in? | **nothing** — the entry says | `summary` |
+| Where do I import it from? | **nothing** — the entry says | `importPath` |
+| How do I call it? | one **example**, or a call in a guide's prose | `dist/examples/<examples[i]>` · `dist/docs/<guide>.md` |
+| What props, and which are optional? | the **example** first; then the **`.d.ts`** *or* the doc — never both | `bundle` present: `dist/dts-bundle/<bundle>` · absent: `dist/docs/<file>` |
+| A setup requirement or gotcha? | the **doc's** prose | `dist/docs/<file>` |
 
-**Don't guess which components or props exist — read the doc files first.**
+Prefix the index's bare values with their tree — `file` → `dist/docs/`, `examples` → `dist/examples/`, `bundle` → `dist/dts-bundle/` — and never rebuild a path from a symbol name.
 
-### Finding the right name
+**Those two middle rows are one question in practice.** You ask how to call it, start writing, and the question turns prop-shaped mid-call — where the second row sends you to a `.d.ts` that may be stubbed (step 5). Take the props off the example first; go to the `.d.ts` only for what it cannot show — optionality, union members, an exact callback signature.
 
-`Read <pkgRoot>/dist/dts-bundle/index.json` — one entry per name, grouped implicitly by its `category` field. Lookup is **exact-match only** — no fuzzy matching. If the exact key isn't there, scan the index you already hold for something close before concluding the name isn't covered.
+**A guide's prose often holds the call.** `PrimaryActions`' bundle stubs its own props type, while `usePatternsNavigate.md` carries `<PrimaryActions label="Add shift" onClick={…} />` verbatim. Check what you have already read before opening anything.
 
-Not every real export is in this index — only names these guides reference. If a needed name genuinely isn't there, **stop and say so rather than falling back to `node_modules`.**
+**`bundle` and a doc props table are mutually exclusive.** With `bundle`, the page's `### Props` is only a pointer; without it, that table marks what is required. Reading both is one hop too many.
 
-### Reading doc files
+**A `.d.ts` names props; it never says what they do.** Wiring and defaults live in prose: `CollectionSearch`'s bundle lists four optional props and no behaviour, while its page says the search term reaches your `fetchData` via `query.search`. When a behaviour question outlives the `summary`, open the page.
 
-`Read <pkgRoot>/dist/docs/index.json` to resolve a name to its doc file — or a `symbols` alias, for cases where the Storybook title doesn't match the export (`ExportTo.md` documents `ExportButton`) — then `Read <pkgRoot>/dist/docs/<file>.md` directly, the whole file, not piped through `head`. It covers more names than the bundle index above — every documented component, not just the curated ones.
+**Artifact not listed?** No `examples` — a hook's usage is usually filed under the component it pairs with (`useEntityPage` → `EntityPage/basic.tsx`). No `importPath` — a guide, or documented but not exported. Nothing at all — a state object you receive rather than construct; its doc is the only source.
 
-**Always check the import statement inside the doc** — not everything comes from `@wix/patterns` (some use subpaths, e.g. `@wix/patterns/provider`).
+### 5 — Traps that make a read wrong
 
-A doc whose index entry has a `bundle` field does **not** list its props — its `### Props` points at that bundle. One without it carries its own table. Either way the doc owns prose, variations, BI events, and the import line.
+**Search inside the file an index named, never across the tree.** A shared shape is re-stubbed in every bundle referencing it, so a tree-wide `grep` returns mostly pointers, and the first hit is rarely the declaration.
 
-### Reading the file the index names
+**Most bundles stub the parent holding the props — 70 of the 105 curated entries do** — and the index says so per entry. **`dist/dts-bundle/index.json` is the triage surface, not merely a fallback for names the docs index lacks:** a component entry carries `ownProps` / `inheritedProps` beside `bytes` and `readWith`, so "is this file the whole answer" is a lookup, not an inspection.
 
-The mechanics of the file an index names — batching the reads, types docs don't cover, one-line stubs that are answers rather than truncation, subpath entry points, cross-references, split compound docs — are in [Reading bundles and docs](dashboard-page/PATTERNS_BUNDLE_READING.md). Read it before your first `dist/dts-bundle/*.d.ts` of the session.
+- `Table` → `ownProps: 5, inheritedProps: 58`, `readWith` naming 3 files. Five of sixty-three.
+- `PrimaryActions` → `ownProps: 0, inheritedProps: 12`. A 470-byte file declaring none of them.
+- No `ownProps` on a component entry means no split — that file *is* the whole answer.
 
-## The Collection → Entity Flow
+A split is not a dead end: the parent is a real file, `readWith` names it, and from 1.469.0 so does the stub inside the file (`Full shape: types/Filter.d.ts`). **Read that one file — one hop, not N.** The rest of `readWith` is types referenced *inside* it, opened only if needed. Judge by the entry's own `bytes`, never `readWithBytes` — `Table`'s are 5,277 against 31,731 — since the combined figure talks you out of a read you should just do. A `…Params` type built from `Pick<>`/`Omit<>` is the same trap in another shape.
 
-A collection page and its item form are **two patterns pages**, not a page plus a modal. Reserve modals for dialogs that neither write nor display a listed record (a delete or discard confirmation, an unsaved-changes prompt); **a create / "add new" form is not one of them** — it writes the record, so it's an `EntityPage` regardless of size. A page that lists nothing is outside this rule — full test in [SKILL.md](../SKILL.md#entity-create-and-edit).
+**When you do need several `readWith` files, read them in one call** — one `Read` per file in a single message. Reads measure ~21 ms each, so ten is a fifth of a second and one round trip. Deciding is what costs: decide once, then batch, and never hop one file per turn. Batching is not a licence to skip the filter, though — a few deliberate reads beat dozens of just-in-case ones.
 
-| Step | What owns it |
-| --- | --- |
-| Navigate from a row / primary action to the item | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
-| Register the route | `PatternsReactRoute` inside `PatternsReactRouter` |
-| Fetch, save, validation, dirty state, skeletons, errors | `useEntityPage({ fetch, onSave })` |
-| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` — `useController`, never `register` |
-| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
-| The individual fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
+**If the parent is large, take the declaration `tsc` uses.** `dist/types/components/CollectionTable/CollectionTable.d.ts` is 5,919 B against the bundle's 20,802 B, carries JSDoc, and states `columns: TableColumn<T>[]` (required) outright. Nothing there is stubbed, so a `grep` for a prop name is reliable. This case only.
 
-Prefer `navigateToEntityPage` over a plain route change — the entity header renders before the fetch resolves. **Every `path` above is page-relative**: the router roots at `path="/"` even on a page scaffolded `route: "shifts"`, so never repeat that name in a `path`, `parentPath`, or `navigateToEntityPage` call — it fails silently. See [ENTITY_PAGE_TOOLKIT.md](dashboard-page/ENTITY_PAGE_TOOLKIT.md).
+The generated files' conventions — which one-line stubs are answers rather than truncation, how entry-point files are scoped — are in `dist/docs/Reading the Doc Indices.md`, worth reading before your first `dist/dts-bundle/*.d.ts` of the session.
 
-Read `EntityPage.md`, `useEntityPage.md` and `usePatternsNavigate.md` before implementing, plus [ENTITY_PAGE_TOOLKIT.md](dashboard-page/ENTITY_PAGE_TOOLKIT.md) for the `useEntityPage` call itself (generics, `onSave`, params). Note `useCreateCollection` is **not** about creating items: it returns a function that initializes collection state.
+### Rules for the reads themselves
 
-## When Patterns Has No Equivalent
+- **Use the exact `file`, `bundle` and `examples` values, prefixed per step 4.** Bundles nest one directory per kind, so `<Name>.d.ts` at the top level is wrong by construction, and an example slug is not derivable from a title.
+- **Extract from the file the index named.** A whole-file `Read` is safe (`bytes` gives the size first); a scoped `grep`/`sed` is cheaper. If an extraction is empty or ambiguous, read the whole file rather than guess.
+- **A `@wix/design-system` name is not yours to look up here.** Use the `wix-design-system` skill; never follow a deep `@wix/design-system/dist/...` path a bundle mentions.
+- **If a name is in neither index, stop and say so**, naming the path that dead-ended. A wrong guess compiles and breaks at runtime.
 
-A concept is only "missing" from patterns after you've checked `dist/dts-bundle/index.json` and `dist/docs/index.json` **and** searched by keyword within what you've read. Then:
+## When Patterns Has No Equivalent
 
-1. Look the component up in `@wix/design-system` via the `wix-design-system` skill.
-2. Render it *inside* the patterns page shell / collection, not as a replacement for it.
-3. If WDS lacks it too, compose from WDS primitives (`Box`, `Card`, `Text`) — never restyle patterns internals, never add another UI library.
+A concept is only "missing" after you have checked both indices **and** searched by keyword in what you have read. Then look it up via the `wix-design-system` skill and render it *inside* the patterns page shell rather than in place of it; if WDS lacks it too, compose from `Box`, `Card` and `Text`. Never restyle patterns internals, and never add another UI library.
 
-Anything page- or collection-shaped (shell, header, table, grid, filters, sorting, paging, row/bulk actions) is patterns' territory. Building one from WDS parts means a skipped lookup.
+Anything page- or collection-shaped is patterns' territory; building one from WDS parts means a skipped lookup.

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

@@ -112,7 +112,6 @@ Presentation success applies across all five stages. Choose both the right **rep
 | **Kanban** | Work moves through meaningful stages. | Stage, workload, and valid movement are understandable. |
 | **Timeline or calendar** | Time, sequence, or scheduling matters. | Upcoming activity, conflicts, and timing are clear. |
 | **Chart** | The user needs to understand a trend or relationship. | The visualization answers a specific business question. |
-| **Summary metrics** | The user needs a quick health signal. | Metrics clarify current conditions and where to focus. |
 
 - Choose the default view that best supports the primary task.
 - Offer another view only when it provides distinct value.
@@ -130,7 +129,7 @@ Choose the smallest interface that gives users enough context and room to comple
 | **Entity page** | The task involves complex details, multi-section editing, history, or related information. | The user has enough space and structure to complete deeper work. |
 | **Inline or expanded row** | The user needs a quick inspection or simple action. | Detail appears without creating a separate workspace. |
 
-Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in [Collection Toolkit](COLLECTION_TOOLKIT.md). Patterns has no side panel; that one is WDS.
+Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in the installed package's `Collection Toolkit.md` guide — reached through [The Discovery Chain](../WIX_PATTERNS_DOCS.md#the-discovery-chain). Patterns has no side panel; that one is WDS.
 
 
 ## Data Success

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

@@ -1,13 +1,13 @@
 # Accessibility Implementation and Review
 
-Use this reference while authoring Editor React Component props and JSX and
-after every JSX edit.
+Use this reference while authoring Editor React Component props and JSX, then
+run the review command once the JSX is complete.
 
 ## Contents
 
 - [Implementation Contract](#implementation-contract)
 - [Review Scope](#review-scope)
-- [Automated Scanners](#automated-scanners)
+- [Automated Review](#automated-review)
 - [Finding Triage](#finding-triage)
 - [Manual Review](#manual-review)
 - [Pre-Fix Checks for Non-Interactive Controls](#pre-fix-checks-for-non-interactive-controls)
@@ -15,29 +15,42 @@ after every JSX edit.
 
 ## Implementation Contract
 
-### Route ARIA Through `a11y`
+### Own Accessibility per Part
 
-Do not add individual public props such as `ariaLabel`, `ariaDescribedBy`, or
-`role`. Use the platform `A11y` type and convert it at the semantic target.
+Use the platform `A11y` type instead of individual public props such as
+`ariaLabel`, `ariaDescribedBy`, or `role`. For each part:
+
+- Prefer a native element.
+- Keep roles, heading levels, keyboard and focus behavior, relationships, live
+  regions, and widget state in component code.
+- Read `a11y.ariaLabel` only when a control has no visible name.
+
+Every `a11y` field that reaches the DOM becomes an editor control. Read only the
+field the part needs and write it as its HTML attribute,
+`aria-label={a11y?.ariaLabel}`. Never spread the whole object.
 
 ```tsx
-import type { A11y, Direction } from '@wix/editor-react-types';
-import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
-
-export type TabsProps = {
-  id: string;
-  className?: string;
-  direction?: Direction;
-  a11y?: A11y;
+import type { A11y } from '@wix/editor-react-types';
+
+type ToggleProps = {
+  elementProps?: { toggle?: { className?: string; a11y?: A11y } };
 };
 
-<nav {...(a11y && convertA11yKeysToHtmlFormat(a11y))}>{tabs}</nav>;
+function Toggle({ elementProps }: ToggleProps) {
+  const { a11y: toggleA11y, ...toggleProps } = elementProps?.toggle ?? {};
+
+  return (
+    <button {...toggleProps} aria-label={toggleA11y?.ariaLabel ?? ARIA_LABELS.toggle}>
+      <ChevronIcon aria-hidden="true" />
+    </button>
+  );
+}
 ```
 
-Apply root accessibility to the elected root. If requirements assign
-accessibility to a named inner part, route it through that part's
-`elementProps.<name>.a11y` contract and convert it on the actual semantic
-element.
+Keep the root's typed `a11y?: A11y` prop even when it reads no field. Destructure
+`a11y` out of an `elementProps` entry before spreading the entry; a spread entry
+records the nested object as a whole. Image alt text comes from the `Image`
+type's `alt` field, not from `a11y`.
 
 ### Provide Accessible Names
 
@@ -53,6 +66,7 @@ Never hardcode an `aria-label` string directly in JSX.
 ```tsx
 // constants.ts
 export const ARIA_LABELS = {
+  toggle: 'Toggle details',
   playButton: 'Play animation',
   pauseButton: 'Pause animation',
 } as const;
@@ -80,36 +94,47 @@ including an icon plus visible text, usually do not need another ARIA label.
 
 ## Review Scope
 
-Run this review after creating or editing JSX.
+Run this review once the JSX is complete and again after each fix pass, at
+most two passes. Do not rerun after a clean result unless JSX changed.
 
-| Request | Scan and inspect |
+| Request | Pass to the command |
 | --- | --- |
-| Specific file | That file and rendered wrappers or shared components it imports |
-| A component name or "this component" | All hand-edited files in its component folder plus relevant shared imports |
-| Full audit | Every component under `src/extensions/site/components/` plus relevant shared imports |
+| Specific file | That file; its component folder is rendered |
+| A component name or "this component" | The component folder |
+| Full audit | `src/extensions/site/components/` |
 
-Exclude `*.generated.ts`; it is regenerated from JSX and CSS.
+`*.generated.ts` is regenerated from JSX and CSS and is never scanned.
 Imported shared components are inspection context, not automatic edit scope.
 Report a confirmed shared-component issue instead of changing a broadly reused
 primitive unless the requested fix requires that shared change and its impact is
 understood.
 
-## Automated Scanners
+## Automated Review
 
 `<SKILL_ROOT>` is the absolute directory containing the active `SKILL.md`. Run
-both commands from the consumer Wix package so dependencies resolve from that
-project. Pass `.tsx` or `.jsx` paths relative to the current directory.
+from the consumer Wix package so dependencies resolve from that project.
 
 ```bash
-node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...
-node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...
+node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>
 ```
 
-Do not treat scanner startup failure as a clean result. The ESLint scanner
-reports JSX accessibility rules. The semantic scanner follows imports up to
-four levels and emits resolution evidence and confidence. Neither scanner
-covers every Editor React Component contract, so complete the manual review
-even when both return zero findings.
+One command, one report. It runs the jsx-a11y ESLint rules, a semantic scanner
+that follows imports and checks the per-part `a11y` contract, and a render
+audit: the component is rendered with `defaultProps` in Node (an SSR check),
+loaded into jsdom with its CSS Modules, and audited with axe-core.
+`component.preview.tsx` must render without falling back to the placeholder.
+
+The JSON report has `summary.line`, then `findings` grouped by rule with a
+count, locations or DOM target, the scanner message, and the axe help link,
+then `notChecked`. Exit `0` means every scanner ran and found nothing, `1`
+means findings, `2` means the review is inconclusive; never treat `2` as clean.
+Exit `2` with `render FAILED (missing-deps)` means `jsdom` or `axe-core` is not
+installed: install them (SKILL.md step 2) and rerun. Exit `2` with
+`render FAILED (loader)` means the audit could not load a module the component
+imports; that is a scanner limit, not a component defect. Change the import
+only if `tsc` also rejects it; otherwise stop and report the loader limit in the
+final summary as a check that could not run. Color contrast, target size, and
+keyboard behavior need a browser and remain manual.
 
 ## Finding Triage
 
@@ -154,39 +179,23 @@ evidence supports.
 
 ## Manual Review
 
-Verify all of the following after triaging scanner output.
-
-### Semantic Targeting
-
-- `a11y` is typed and converted on the correct semantic element.
-- Wrappers and polymorphic components preserve their documented semantics.
-- Configurable heading or tag choices reach the rendered element.
-- Extension overrides preserve generated accessibility fields.
-
-### Names and Visual Content
-
-- Icon-only controls have configurable or stable system-owned names.
-- Visually hidden text remains in the accessibility tree when needed.
-- Meaningful images and icons are named; decorative repetitions are hidden.
-- Accessibility strings are not hardcoded directly in JSX.
-
-### Hidden Content and Focus
-
-- Hidden or collapsed state agrees across visuals, focusability, and the
-  accessibility tree.
-- Invisible content cannot receive focus unless the interaction requires it.
-- Disabled and inert states behave consistently for keyboard and assistive
-  technology users.
-
-### Interaction and Structure
-
-- Interactive-looking elements use native semantics or complete role, focus,
-  and keyboard behavior.
-- `onClick` on a non-interactive tag is checked, including conditional spreads.
-- Nested interactive children and existing focus management are inspected
-  before semantics are added to a wrapper.
-- Lists, headings, landmarks, tabs, menus, dialogs, and breadcrumbs keep their
-  intended structure.
+In the default rendered state the command checks names, alt text, ARIA
+validity, nesting, list and heading structure, hidden-but-focusable content,
+the `a11y` contract, and SSR safety. Verify what it cannot see:
+
+- Every meaningful non-default state (expanded, selected, playing, error,
+  empty, hover/focus) keeps correct names, focusability, hidden state, and
+  structure; the command audits only the default render.
+- Wrappers and polymorphic components preserve their documented semantics;
+  extension overrides preserve generated accessibility fields.
+- Accessible names describe the action, and visually hidden text that carries
+  meaning stays in the accessibility tree.
+- State hidden through `--display` or transforms agrees with focusability and
+  the accessibility tree; disabled and inert states behave consistently.
+- Custom widgets (tabs, menus, dialogs, sliders) implement their keyboard
+  pattern: arrow keys, Home/End, Escape, roving `tabIndex`.
+- Interactive controls have a hit area of at least 24×24 CSS px and visible
+  focus.
 - The root implements the direction contract, and every `ReactNode` slot
   isolates nested content with `dir="ltr"`.
 
@@ -211,12 +220,13 @@ Prefer a native element when it preserves product behavior.
 
 The accessibility review is complete only when:
 
-- both scanners start successfully;
-- every finding is triaged;
-- confirmed issues are fixed when safe;
-- the manual review is complete; and
-- both scanners are rerun on every changed `.tsx` or `.jsx` file.
+- the last run exited `0` or `1`; exit `2` is acceptable only for a reported
+  `loader` limit;
+- every finding is triaged and confirmed issues are fixed when safe;
+- the command was rerun after the last fix pass; and
+- the manual review is complete.
 
+After two fix passes, stop and report the remaining findings with their triage.
 Preserve visual and runtime behavior. Fix the semantic owner: root, named inner
 part, shared primitive, or call site. Then return to the main workflow for the
 Wix build, manifest generation, TypeScript check, and relevant project tests.

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

@@ -42,8 +42,9 @@ export type PlanCardProps = {
 
 Rules:
 
-- Route all ARIA attributes through `a11y`; do not add individual `ariaLabel`,
-  `role`, or similar props.
+- Follow `ACCESSIBILITY.md`. Expose only `ariaLabel`, for a control without a
+  visible name, through the typed `a11y` contract. Keep semantics and state in
+  code. Do not add one-off ARIA props or spread the whole object.
 - Expose only content and behavior that the site owner controls. Keep derived
   values internal.
 - Add only callbacks required by the component specification. Use supported SDK