@wix/agent-skills 1.30.0 → 1.31.1

package/package.json

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

package/skills/wix-app/SKILL.md

@@ -28,9 +28,9 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
     - [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
 
     A filtered table with no drill-in and no working filters is what gets built when nobody states the requirement — the most common way a generated dashboard disappoints. The aggregate is the judgment call; the drill-in and the filters are not.
-  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Followed [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md): found the page templates the installed `@wix/patterns` ships, chose one with its `Page Templates.md` guide — which pages the workflow above needs, **and where the rows come from** (your own fetch, or a CMS collection) — read that template's page, and copied every file in its `templateFiles`. Composing the page shell, provider nesting, or router wiring from scratch when a template already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the template doesn't cover, not a replacement for starting there. The reverse holds too: a template replaces composing the shell, never the discovery chain, so every symbol it doesn't show still goes through the next gate.
-  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. Then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls), `dist/dts-bundle/` (types) and `dist/templates/` (whole pages) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
-  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the index** which single artifact answers the question you actually have — `importPath`, `examples`, or `bundle` — and read only that one, per [Component Selection Order](#component-selection-order)'s "the short version". State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an `importPath` the index already gave you, is the failure this gate exists to prevent.
+  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Followed [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md): found the page templates the installed `@wix/patterns` ships, chose one with its `Page Templates.md` guide — which pages the workflow above needs, **and where the rows come from** (your own fetch, or a CMS collection) — read that template's page, and copied every file `--templates` lists for it. Composing the page shell, provider nesting, or router wiring from scratch when a template already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the template doesn't cover, not a replacement for starting there. The reverse holds too: a template replaces composing the shell, never the discovery chain, so every symbol it doesn't show still goes through the next gate.
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. Then resolve every patterns name you plan to write in **one** `node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call: per name, it prints the import, the examples and the one props file. Upgrade `@wix/patterns` if `dist/docs/index.json` is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls), `dist/dts-bundle/` (types) and `dist/templates/` (whole pages) trees — never from `src/`, `dist/esm/`, `dist/types/`, or any other path inside the package. A prop a bundle has stubbed is in the file its stub names (`Reading the Doc Indices.md`).
+  - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the lookup output** which single artifact answers the question you actually have — the import line, an example, or the props file — and read only that one, per [Component Selection Order](#component-selection-order)'s "the short version". State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an import line the lookup already gave you, is the failure this gate exists to prevent.
 
     For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
 - [ ] **Step 3:** Checked API references; used MCP discovery only for gaps
@@ -111,11 +111,10 @@ Whole pages are the package's too: the router wiring for a multi-page extension,
 `@wix/patterns/schema`, where the schema supplies fetch, filters, columns and the form — both ship
 as page templates. See [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md).
 
-The short version — probe `<pkgRoot>/dist/docs/index.json` first (`grep`/`python3`, not a
-whole-file `Read`), then the guides it lists. From
-there the index answers per symbol: `importPath` is the import line (no read needed), `examples`
-names the worked call, and `bundle` says whether props live in a `.d.ts` or in the doc's own
-table. Read the one artifact your open question needs. Resolve `<pkgRoot>` once per session
+The short version: list every patterns name you plan to write, and resolve them all in one
+`node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call, not one index probe per name.
+Its output gives each name's import line (no read needed), its worked examples, and the one
+file that holds its props. Read the one artifact your open question needs. Resolve `<pkgRoot>` once per session
 ([Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites)) and reuse it.
 
 **Opening one item from a collection uses an editable `EntityPage` by default; create/edit flows also use `EntityPage`, never a dashboard modal** — see

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

@@ -35,7 +35,7 @@ The CLI generates the folder, the page's component file (`<page>.tsx`, the build
 
 **Before writing that UI:** copy in the installed `@wix/patterns` page template that matches, per [DRAFT_TEMPLATE.md](dashboard-page/DRAFT_TEMPLATE.md) — don't compose the shell from scratch.
 
-**Then, for whatever the template doesn't cover:** probe `<pkgRoot>/dist/docs/index.json` once with `grep`/`python3` — never a whole-file `Read`, which truncates silently ([Prerequisites](WIX_PATTERNS_DOCS.md#prerequisites)). Its `importPath`, `examples` and `bundle` decide whether you open anything else. Each Bash call is a fresh shell — re-set the path variable every time.
+**Then, for whatever the template doesn't cover:** list every patterns name you'll add, and resolve them all in one `node <pkgRoot>/bin/patterns-lookup.cjs <name…>` call ([WIX_PATTERNS_DOCS.md § 1](WIX_PATTERNS_DOCS.md#1--the-index)). Its import, examples and props file decide whether you open anything else. Each Bash call is a fresh shell — re-set the path variable every time.
 
 ## Capabilities
 

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

@@ -12,23 +12,21 @@ Then check the install, two ways: `ls <pkgRoot>/dist/dts-bundle/index.json`, and
 
 **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.
 
-**Patterns API facts come from four published trees only:** `dist/docs/` (pages), `dist/dts-bundle/` (types), `dist/examples/` (worked calls), `dist/templates/` (whole pages). 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.
+**Patterns API facts come from four published trees only:** `dist/docs/` (pages), `dist/dts-bundle/` (types), `dist/examples/` (worked calls), `dist/templates/` (whole pages). 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. That includes `dist/types/`: `tsc` reads it, but its files import their props from sibling files, so it answers no props question in one read.
 
 ## The Discovery Chain
 
 ### 1 — The index
 
-**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.
+**Resolve every patterns name you plan to write in one call:**
 
-Start here rather than the bundle index: it carries every documented name *and* the guides.
-
-- **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.
+```bash
+node <pkgRoot>/bin/patterns-lookup.cjs Table useTableCollection stringsArrayFilter DateRangeFilter
+```
 
-**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.
+The package ships this script, so it matches the installed indices. For each name it prints the import, the examples and the **one** file for props. Its `summary` line usually answers the question, so step 4 needs no read. A name in neither index makes it exit 1, with near matches. `--templates` lists the page templates. **List the names first.** Each name you add later costs another round trip, and those round trips are this step's whole cost.
 
-**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.
+**If `<pkgRoot>/bin/patterns-lookup.cjs` is missing** (an older `@wix/patterns`), probe `<pkgRoot>/dist/docs/index.json` with one `grep`/`python3` call covering every symbol, and match keys and `symbols` aliases exactly. Never `Read` it whole: it truncates silently. A name not in it may still be in `dist/dts-bundle/index.json`.
 
 ### 2 — Composition, once per session
 
@@ -46,48 +44,11 @@ Each guide's index entry carries `relatedComponents`; every name in it resolves,
 
 ### 4 — Read only what answers your question, then stop
 
-| 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>` |
-
-Prefix the index's bare values with their tree — `file` → `dist/docs/`, `examples` → `dist/examples/`, `bundle` → `dist/dts-bundle/`, `templateFiles` → `dist/templates/` — and never rebuild a path from a symbol 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.
-
-**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.
-
-**`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.
-
-**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.
-
-**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.
-
-### 5 — Traps that make a read wrong
-
-**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.
-
-**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.
-
-- `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.
-
-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.
-
-**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.
-
-**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.
-
-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.
-
-### Rules for the reads themselves
+**`Read <pkgRoot>/dist/docs/Reading the Doc Indices.md` once per session**, before your first read past the lookup output. The package keeps it in step with its own indices. It says which file answers which question, what a one-line stub in a `.d.ts` means, and how to follow a stubbed prop to the file that declares it. The rules below are about how many reads you make:
 
-- **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.
+- **Read the one artifact your open question needs.** Check what you have already read first: a guide's prose often holds the call.
+- **Decide once, then batch.** When you need several files, read them in one message, one `Read` per file. Never hop one file per turn. Deciding is what costs, so a few deliberate reads beat dozens of just-in-case ones.
+- **Extract from the file the lookup named.** 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.
 

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

@@ -1,9 +1,8 @@
 # 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.
+> **Scope.** [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) gives you the page; this file finds the method
+> and *field names* for its data. Read it before Step 3's MCP discovery. The installed package is
+> the version your code compiles against.
 
 ## Where the types actually live
 
@@ -47,7 +46,14 @@ 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:
+the uncertain ones, **in one pass**. List the types and fields first, then print them with one call
+per file. A grep per question is a round trip each:
+
+```bash
+awk '/^(interface|type) (Payment|RegularPaymentDetails)[ <{=]/,/^}/' $E/index.typings.d.mts
+```
+
+Failure modes that recur:
 
 **Deprecated fields still compile.** On `RegularPaymentDetails`, `paymentMethod` carries
 `@deprecated Use paymentMethodName.buyerLanguageName instead` — the deprecated one is a bare code,
@@ -93,15 +99,13 @@ a batch endpoint given `[]` is a wasted round trip at best.
 `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`.
+declaration, not from memory: order payment status has ten, `PENDING_MERCHANT` and
+`PARTIALLY_REFUNDED` among them.
 
 ## 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.
+URL of whatever page you landed on and read that view — it answers two of the four differences.
 
 **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

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

@@ -6,17 +6,14 @@ Go through [WIX_PATTERNS_DOCS.md § Prerequisites](../WIX_PATTERNS_DOCS.md#prere
 
 ## 1. Find the templates
 
-Templates are docs-index entries with `category: "Templates"`, and each lists every file of its page in `templateFiles` (relative to `dist/templates/`). One probe lists them all with the guide that chooses between them:
+One call lists every page template with its files, plus the guide that chooses between them:
 
 ```bash
-python3 -c "
-import json; i = json.load(open('<pkgRoot>/dist/docs/index.json'))
-for k, e in i.items():
-    if e.get('category') == 'Templates' or e.get('relatedTemplates'):
-        print(k, '|', e.get('templateFiles') or e.get('relatedTemplates'), '|', e.get('summary', '')[:200])
-"
+node <pkgRoot>/bin/patterns-lookup.cjs --templates
 ```
 
+It also takes names (`--templates Table useTableCollection …`), so the patterns names you already know you'll need can go in the same call ([WIX_PATTERNS_DOCS.md § 1](../WIX_PATTERNS_DOCS.md#1--the-index)). If the script is missing (an older `@wix/patterns`), list those entries from `<pkgRoot>/dist/docs/index.json` in one probe.
+
 **No `Templates` entries means the install predates them — upgrade `@wix/patterns`.** Do not rebuild a page from memory or from an older copy of this skill instead: the templates exist so the shell, provider nesting and router wiring come from the package.
 
 ## 2. Choose, then read the chosen template's page
@@ -48,7 +45,7 @@ wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","rout
 
 `route` takes no leading slash — `support-tickets`, not `/support-tickets`. See [Dashboard Page → Scaffold](../DASHBOARD_PAGE.md#scaffold).
 
-Then copy **every** file in `templateFiles` into the generated folder (`src/extensions/dashboard/pages/<feature>/`). They import one another by relative path, so keep their names relative to each other; one file on its own does not compile.
+Then copy **every** file `--templates` lists for it into the generated folder (`src/extensions/dashboard/pages/<feature>/`). They import one another by relative path, so keep their names relative to each other; one file on its own does not compile.
 
 - The template's `page.tsx` is the entry file, and the CLI generated none by that name: put its contents into the component file the builder's `component` path points at (e.g. `employee-shifts.tsx`), and add no separate `page.tsx`, which nothing loads. Leave the builder file and the `src/extensions.ts` registration as the CLI wrote them.
 - Rename `Items` / `Item` to your feature and entity, in file names and identifiers alike.

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

@@ -8,7 +8,7 @@
 ## Why guessing here always fails
 
 `useTableCollection()` returns a `TableState`. For the members themselves, read the declaration the
-index names — `Read <pkgRoot>/dist/dts-bundle/index.json`, then its `file`. Reading them is not the
+index names: `patterns-lookup.cjs TableState`, alongside the other names you need, then the file it prints. Reading them is not the
 hard part; the hard part is that several plausible members don't exist at all, and one that does
 means something other than its name suggests (see
 [Four that bite in practice](#four-that-bite-in-practice)).
@@ -24,7 +24,7 @@ That is a documentation abridgement, not the declaration your code compiles agai
 `dist/types/index.d.ts`, which re-exports the **fully typed** `CollectionState` from
 `@wix/bex-core` — no index signature. So `state.collection.…` is properly typed, a wrong member is a
 compile error at the access, and reading `state.collection.status.status` to debug a stuck table is
-sound. See [WIX_PATTERNS_DOCS.md § 5](../WIX_PATTERNS_DOCS.md#5--traps-that-make-a-read-wrong).
+sound. See `<pkgRoot>/dist/docs/Reading the Doc Indices.md` for what a stub means.
 
 Prefer a typed member on `TableState` itself anyway — it is the object the hook hands you, and the
 table's own view of the collection.
@@ -129,5 +129,6 @@ cursor: response.pagingMetadata?.cursors?.next || undefined,
 extend. Cursor mode also accepts a separate `fetchTotal`, since a cursor-paged response carries no
 total; build its filter exactly as the page's or the count disagrees with the rows it counts.
 
-Look any of these up yourself with `Read <pkgRoot>/dist/dts-bundle/index.json` and the `file` path it
-gives; the index is the single source of truth, and it moves between versions.
+Look any of these up yourself, all in one `patterns-lookup.cjs` call
+([WIX_PATTERNS_DOCS.md § 1](../WIX_PATTERNS_DOCS.md#1--the-index)), and read the file it names. The
+index is the single source of truth, and it moves between versions.

package/skills/wix-headless-kit/SKILL.md

@@ -24,8 +24,9 @@ doesn't express — or once the site exists and the work turns to managing or ex
 - **Shipped code is the implementation.** Every vertical ships in the repository's
   `wix-headless-templates` skill (`skills/wix-headless-templates/<vertical>/`), not in this skill's
   folder. `node <SKILL_ROOT>/install/templates.mjs` prints where that skill is: the sibling folder
-  `<SKILL_ROOT>/../wix-headless-templates/` when the install carried both skills (the cold start
-  does), else a one-time fetch into `<SKILL_ROOT>/templates/` (a second); every script below
+  `<SKILL_ROOT>/../wix-headless-templates/` when it was installed beside this skill (the cold start
+  installs both; a plugin may not), else a one-time fetch into `<SKILL_ROOT>/templates/` (a git
+  clone of the skill's repository, a second); every script below
   resolves it the same way. **Every `templates/...` path in this document is relative to that
   printed root** — there is no `templates/` folder inside this skill when the sibling exists.
   The folder stays with the project (only the composed `project/` scaffolds are left out of its
@@ -100,8 +101,8 @@ cases of step 3, with the `next` for each) and the two identities a project has
 as and whose dashboard manages the business). They are one site, except on a **migration preview**
 (`guides/migration.md`), where the env names the site being migrated. Every script here reads that
 context; the site a call targets is never guessed from the config alone. Then fetch the shipped
-code once: `node <SKILL_ROOT>/install/templates.mjs`. It prints the folder;
-the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
+code once: `node <SKILL_ROOT>/install/templates.mjs`. It prints the folder; the `templates/…`
+paths below are relative to that folder, never assumed under `<SKILL_ROOT>`.
 `node <SKILL_ROOT>/install/check.mjs` says whether the skill or its templates have a newer version
 and prints the update commands; it changes nothing.
 
@@ -166,9 +167,9 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    folder's config does, the site holds the content already; the frontend reads what is there
    (step 3's attach path), and only content the brief supplies or describes is added to it.
 3. **Set up the project, in its folder** — one deterministic call, the same for an empty folder
-   and for a project already on disk; **the folder decides** what it does, from five file facts:
+   and for a project already on disk; **the folder decides** what it does, from a few file facts:
    `wix.config.json`, its `site.outputDirectory`, the migration variables in `.env.local`,
-   `package.json`, `index.html`. `node <SKILL_ROOT>/install/context.mjs` prints the shape it reads
+   `package.json`, `index.html` (at the root or in `public/`), `src/pages/`. `node <SKILL_ROOT>/install/context.mjs` prints the shape it reads
    and the `next` for it. **The brief is the instruction**: what it asks to switch on is installed
    on the site the folder names, without asking again. Ask only when acting would create a second
    site for a folder that already has one, or when a cleanup seems needed.
@@ -189,6 +190,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    | a config whose `.env.local` declares an active editor migration (`EDITOR_MIGRATION_STATUS=ACTIVE`), with or without the blank Astro starter the download carries | **migration** → migrate | the shipped code into the starter (or the composed template around a bare config), deployed with the migrated site's app as the client, the install starts; `ready_for_brand_layer` says `mode: "migrate"`, the parent as `siteId`, the child as `deploySiteId` (`guides/migration.md`) | no, ever |
    | a config, no frontend | **config-only** → refuses | the site exists and has no frontend yet: `attach.mjs` (below) takes the site from the config, reuses its hosting, scaffolds and deploys. That config is what `init` leaves behind, and `init` always creates a site: this site was made for this run and is empty | **yes**: draft the plan as for create, then `attach.mjs --plan` |
    | a config and a frontend (a `package.json`, or `index.html` inside the folder `site.outputDirectory` names) | **wix-project** → refuses | iterate: never scaffold, `init` or reseed. `deploy.mjs <vertical…> --stack <stack>` adds a solution (the client id comes from `.env.local`, the config as the fallback), then ONE `npm install`; a change is file edits; then release | no |
+   | a config, a `package.json`, `public/index.html` and no `src/pages/` (a site published through the drop flow, on its Wix Dev Machine) | **static-in-astro** → refuses | the pages stay plain files in `public/`: `deploy.mjs <vertical…> --stack static --out public` puts the REST layer in `public/js/wix/`, the pages are wired in place (reference mode), and no Astro pages are added; release with `build` then `release`, the URL stays | no |
    | a config, `index.html` at the root, no `package.json` (a site published through the drop flow and downloaded) | **published-static** | the config's site, no `init`: `site/` becomes the upload, the REST layer deploys into `site/js/wix/`; the `next` says to move the pages, styles and assets in; release keeps the URL | no |
 
    **Who decides the seed: where the site came from, never the brief's wording.** A site made
@@ -201,7 +203,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    id in the brief or by `--site`, a project linked to it, a migration's parent (attach reports
    `siteOrigin: "given"`) — holds content the run did not make: seed only what the brief
    **supplies or asks to add** (`attach.mjs --plan plan.json`, or the vertical's seed module from
-   the project root: `node <SKILL_ROOT>/templates/<vertical>/seed/seed-<vertical>.mjs plan.json`),
+   the project root: `node <templates>/<vertical>/seed/seed-<vertical>.mjs plan.json`, `<templates>`
+   being the folder `install/templates.mjs` printed),
    and never invent content for it. "A new storefront for my toy store" describes the business,
    not content to add: nothing is seeded. Read an existing site first either way
    (`seed/read-site.mjs`). Seeds are additive and idempotent by name; nothing on a site is ever
@@ -253,9 +256,12 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    INSTRUCTIONS and the shared floors — `templates/shared/DESIGN.md` +
    `templates/shared/CONTENT.md` — now (not earlier — their contracts matter only from this
    step on); the hook/DTO
-   contracts are inlined there, so don't open the shipped files themselves. **Author your
-   surfaces in as few messages as possible** — batch multiple Write calls in one message
-   (components are independent files); don't pay a round-trip per file.
+   contracts are inlined there, so don't open the shipped files themselves.
+   **A frontend that already exists gets the minimum.** When the run wires pages that were
+   there before it (a dropped mock, an adopted site, a published static site), do the least that
+   makes them work: connect each control the pages show to the shipped code, and add only what a
+   control can't work without. Anything more the vertical offers is added only when the brief
+   asks for it; name it in the closing message.
    If the brief needs a core operation that shipped code does not cover, read
    `templates/shared/CUSTOM_OPERATIONS.md` before writing it. Use one documented path and
    implement it; do not reverse-engineer SDK internals.
@@ -286,7 +292,9 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    that fix it: **Accept payments** `https://manage.wix.com/dashboard/<siteId>/wix-cashier/payments`
    (connect a payment method; "manual payments" is enough for free and pay-in-person flows) and
    **Upgrade the plan** `https://www.wix.com/upgrade/website?metaSiteId=<siteId>` (online payments
-   need a premium plan). Both are the owner's steps, not a defect in the site. **Copy the live URL verbatim from the
+   need a premium plan). Both are the owner's steps, not a defect in the site. When the run started
+   from the owner's own pages, name what those pages promised that the released site does not do.
+   **Copy the live URL verbatim from the
    `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
    a 404). Before you sign off, run the feedback self-check over the whole session
    (`guides/feedback.md`): anything that cost more turns than it should have, including what you
@@ -305,7 +313,7 @@ how to close such a run. A public site is still better served by managed Astro;
 close.
 
 Without a machine at all, or when the install, the CLI or the login is blocked where you are,
-read `<SKILL_ROOT>/guides/no-machine.md`: the same run, step by step, as the Wix API calls the
+read `<SKILL_ROOT>/guides/api-run.md`: the same run, step by step, as the Wix API calls the
 scripts make and the files beside this skill that carry the contracts.
 
 ## Verticals

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

@@ -0,0 +1,178 @@
+# The kit's run as Wix API calls
+
+Read when the commands this skill is built on cannot run where you are, or stopped: your shell
+can't reach Wix, there is no shell, or the install, the
+CLI or the login is blocked. Wix is then reachable through the Wix MCP: every call below is an
+`ExecuteWixAPI` call, and files reach the site through the upload recipe. It walks the run of
+SKILL.md step by step and names, for each, the Wix API call the CLI or the script performs and the
+file beside this skill that carries the contract; where a script can run where you are, it says so.
+
+## Where these skills are
+
+This skill is one of a set, and the guide reads from three of them:
+
+- `{SKILL_ROOT}` — this skill, `wix-headless-kit`: the run, its guides, the Verticals table.
+- `{TEMPLATES}` — `wix-headless-templates`: the shipped, verified code per Wix Business Solution,
+  one folder each, with its `INSTRUCTIONS.md` (the contracts), `seed/` (the seed script and
+  `SEED.md`) and `rest/` (the data layer over plain `fetch`). Not every install carries it (a
+  plugin may leave it out): it is installed beside this skill, or fetched to
+  `{SKILL_ROOT}/templates/` by `node {SKILL_ROOT}/install/templates.mjs` (a git clone), or installed
+  with `npx skills@latest add wix/skills --skill wix-headless-templates`; with none of those, read
+  online at `https://www.wix.com/skills/wix-headless-templates/{path}`.
+- `{MANAGE}` — `wix-manage`: REST recipes to configure and manage a site's business solutions, one
+  recipe per operation with the exact endpoint and payload; its `SKILL.md` is the index.
+- `{DOCS}` — `wix-docs`: how to look up the Wix API and SDK documentation and confirm a method's
+  exact shape before writing a call.
+
+Installed, they sit beside each other wherever your client keeps them: under `.agents/skills/` after
+`npx skills add`, or in a plugin's folder. Read them from disk when they are there. Online, they are
+published alongside each other under the same names (the registry also serves each without its
+`wix-` prefix, `headless-templates` for `wix-headless-templates`, which is the `base` its manifest
+shows; both forms resolve), each with a manifest of its files, and in the
+`wix/skills` repository on GitHub under `skills/{skill}/`; a sandbox that reaches GitHub has the
+whole set on disk from a clone. Online pages are read with the Wix MCP's `ReadFullDocsArticle`
+when it is connected: a client's web fetch may open only URLs the user gave or a search returned.
+
+What such a run does not produce: the Astro build and its release. Those need a machine with the
+CLI. Everything else the kit does to a site, it does through calls you can make, the frontend
+included: step 5 ships it as static files.
+
+## 0. Identity
+
+Every call below runs as the site owner, with whatever identity your host gives you: the Wix
+MCP's `ExecuteWixAPI` carries the user's login; an API key from the user's account goes in the
+`Authorization` header of any call, as `{MANAGE}/SKILL.md` describes; a site token from the Wix CLI
+works the same way when the user runs the CLI for you. The site's OAuth app (`client_id`) mints
+visitor tokens only, which cover what a visitor may see and nothing here.
+
+## 1. The brief → the solutions
+
+Unchanged from SKILL.md step 2 and its Verticals table: the brief names the business, the table
+names the solutions it needs. Read each solution's `{TEMPLATES}/{solution}/INSTRUCTIONS.md` for
+what it covers and `{TEMPLATES}/{solution}/seed/SEED.md` for what a seeded site holds.
+
+A brief that needs no solution (a game, a landing page, a tool) is a run of two steps: the site
+(step 2, with no `seedOptions`) and the frontend (step 5). No apps, no seed.
+
+## 2. The site
+
+The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
+with `origin: agent-<your-id>`, a name, and the solutions to install as `seedOptions`. The recipe
+is `{MANAGE}/references/sites/create-headless-site.md`; it returns the `metaSiteId` and the
+site's OAuth client `appId`. Do not create a site any other way: a project from Create Project or
+a template is neither headless nor publishable, and a later run with a machine cannot attach to it.
+
+A site that already exists (the brief names it) is read first, never seeded unasked: SKILL.md
+step 2 and `{SKILL_ROOT}/guides/existing-site.md` apply as written.
+
+## 3. The apps
+
+A solution the provision call did not install, or a capability's app (Members Area, Forms,
+Restaurants, Donations, FAQ), goes on with the Apps Installer:
+`{MANAGE}/references/app-installation/install-wix-apps.md`. The app ids are in each
+`seed-{solution}.mjs`, which installs them before seeding.
+
+## 4. The seed
+
+`seed-{solution}.mjs` is a sequence of REST calls, and `SEED.md` is its contract: the plan shape
+(what to create, how many, which images), the order the entities need, and the traps the script
+encodes (a Bookings service needs a category to be visible and takes resource ids, not staff ids;
+a Forms field is registered by its `validation` block; a product's choice photos are linked after
+the gallery holds them; right after a bulk create a product's own stock summary can still read
+`OUT_OF_STOCK` while its inventory items are already stocked, so check the items (Query Inventory
+Items) and create only the missing ones, as `SEED.md` says, where `ALREADY_EXISTS` means stocked; stock that isn't counted, such as "made to order", is
+`inStock: true`, never a missing quantity, which leaves the product unbuyable). Read `SEED.md`
+before the first create call: it maps the brief's words to the fields. Those fields are the
+script's input, not the request: the body each create sends is built in the script (for products,
+`bulkCreateProducts` in `seed-store.mjs`: the description as rich-text nodes from `mkDesc`,
+`productType` with `physicalProperties`, the stock as `inventoryItem`), so read that function before
+the first create. On a site this run created, the store's currency is `SEED.md`'s `currency` rule,
+the one the brief or the user's own pages state (a page priced "$68" is USD), set before the
+products and without asking; a confirmation before a currency change is for a store the user
+already runs. Then read the script for any call `SEED.md` only names, and make the same
+calls through `{MANAGE}`'s recipe for each (services, products, posts, events, collections). Keep
+the script's rules: create, never delete, and report what the site already held. A photo already in
+the site's Media Manager, such as one the user uploaded, goes in by its file id (`imageMediaId` in
+`SEED.md`), as it is: an import by URL would copy it. A photo on a site the user dropped is served
+with the drop, not from the Media Manager: it goes in by its live URL, imported once through
+`{MANAGE}/references/media/upload-media-to-wix.md`, and the file id the import returns is what the
+product or service takes. Image prompts need the Media Manager; without
+it, products and services stay text-only, say so. The scripts read
+a response body directly; `ExecuteWixAPI`'s `wix.request` returns `{ status, data }`, and the body
+is `data`. A generated image is billed when it is generated, so a read of the wrong level discards
+a paid image.
+
+## 5. The frontend
+
+The run is not done until the pages use what the backend holds: every control the page shows for
+it (add to cart, the cart, book, submit) works on the live site. A backend with untouched pages is
+half a run.
+
+The Astro pages cannot be released here: that is a run with a machine and a CLI login, which
+attaches to this site (`guides/existing-site.md`) rather than making a new one. What ships from here
+is static files, dropped onto the site from step 2 through
+`{MANAGE}/references/sites/upload-static-site.md`: the Wix MCP's upload tool, or a script that
+downloads what the site serves, edits it and drops it back, so only what changed is written. Which
+files depends on whether the compose can run, and on what writing them costs: when files reach the
+upload tool as files (its `attachments`), anything on your disk travels as it is; when they don't,
+every file you send is text you write, and the smallest set wins.
+
+**When the compose can run** (the skills on disk, Node, and npm reachable, for the TypeScript compiler it fetches), the frontend is the kit's own shipped code. The compose
+`{SKILL_ROOT}/install/deploy.mjs {solution} --stack static --out site --client-id {appId}` fetches the
+templates and writes the solution's REST data layer and stores to `site/js/wix/` as plain ES modules
+(`guides/reference-mode.md`, the static site): the transport, the cores, the state machines, verified,
+with the `.ts` beside each `.js` for reading. You write the pages and the rendering on those stores,
+imported relative to `site/` in a `<script type="module">`, and nothing of the data layer. The drop
+takes the complete file set in one call and a response has a hard size limit; the recipe's "Change it
+later" section downloads what the site serves, so a later drop adds files to a live set without
+resending what is already there.
+
+**When it cannot**, or when its output would all have to be written out by hand, a page that loads
+the Wix SDK from a package CDN and talks to the site as a visitor. One file per call, a few hundred lines, written in full inside that call: a response has a
+hard size limit, and a call that carries the whole frontend at once exceeds it. A second file joins
+the first the recipe's way, "Change it later": the same call downloads the live set and drops the
+union. The
+SDK comes from a pinned package URL, `https://esm.sh/@wix/sdk@{version}` and the solution's package
+(`@wix/bookings`, `@wix/stores`, `@wix/blog`, …); the client is
+`createClient({ modules: { … }, auth: OAuthStrategy({ clientId }) })` with the `appId` the provision
+call returned, and the SDK mints and refreshes the visitor token itself. Markup, a render function
+per state, the event handlers: that is what you write. Keep what the page shows to what the site
+holds; nothing invented, as in SKILL.md step 4.
+
+**The calls**, on that second path, take their shape from the kit's own transport for the solution,
+`{TEMPLATES}/{solution}/app/wix/{solution}/*.ts` (`services.ts`, `booking.ts`, `catalog.ts`, …,
+with `{TEMPLATES}/shared/app/wix/sdk.ts` for the client wiring): those files call the same SDK
+modules the page imports, and they are verified. Copy the form of the call, not the file. A page
+that talks to Wix over plain `fetch`, with no SDK, takes them from the REST twins instead:
+`{TEMPLATES}/shared/rest/client.ts` (the visitor token and the request) and
+`{TEMPLATES}/{solution}/rest/*.ts` (the calls; for a store, `storefront/rest/cart.ts` and
+`storefront/rest/catalog.ts`). Read those files by name; the manifest and the solution's whole
+`INSTRUCTIONS.md` are not needed to find them. The
+cores beside them (`*-core.ts`) hold the rules the page needs and nothing else does: which fields
+to read, how a price or a duration is formatted, which slot is bookable, how an id is read. Copy
+those core functions into the page as they are, with only the types removed (`cart-core.ts`'s
+`toLine` and `toCart`, the price formatter, `rawId`), and run every API response through them: a
+raw field read by hand is where a page breaks (a product name is a translatable object, a cart
+line's quantity is `quantityInfo.confirmedQuantity`). What you write is the markup, the rendering
+of what the cores return, and the event handlers.
+
+**A call those files don't cover** is confirmed before it is written, the way `{DOCS}` describes:
+the method's SDK page, and when the page and the package disagree, the package's own type
+declarations (the `@wix/auto_sdk_{solution}_<module>` package the solution package depends on,
+its `index.d.ts`) are the truth. Two shapes that recur, as examples of what the types settle and
+the kit's files already encode: SDK query methods return a query builder finished with `.find()`;
+and an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
+`rawId`). Dates travel as local wall-clock strings in the business time zone. A page cannot be
+opened here, so a wrong shape fails silently in the browser. Check the data code before the upload:
+get a real response through `ExecuteWixAPI` for each call the page makes, run the page's data code
+on it in your sandbox's Node, and look for names, prices and quantities in the output, not
+`[object Object]` or `undefined`. The cart's calls run as a visitor, which `wix.request` (the
+owner) is not: in the script, mint a visitor token with the site's public client id as
+`shared/rest/client.ts` does (`POST https://www.wixapis.com/oauth2/token`, `grantType: "anonymous"`),
+send the cart calls with it through `fetch`, add one product and read the cart back.
+
+## 6. Closing
+
+SKILL.md step 5's closing, with two additions: the site id, so a run with a machine attaches to this
+site (`guides/existing-site.md`) instead of making a new one; and, when files were dropped, that a
+change re-drops the whole set.

package/skills/wix-headless-kit/guides/existing-site.md

@@ -7,7 +7,8 @@ is the create flow's job on a site made for the run — a folder holding only a
 is that case too: `init` made the site; SKILL.md step 3). (A project downloaded from Wix whose `.env.local` declares a
 migration is the other way to arrive at an existing site: `guides/migration.md`; the reading
 part below applies there too, against the migrated site.) `<SKILL_ROOT>` is the installed skill folder; the shipped code is
-under `<SKILL_ROOT>/templates/` (SKILL.md, "The run").
+in the folder `node <SKILL_ROOT>/install/templates.mjs` prints (`<templates>` below; SKILL.md, "The
+model").
 
 **Read the site, then run attach.** First, one call tells you what
 the site is — its name, currency, and the Wix apps installed on it:
@@ -46,7 +47,7 @@ for: what the chosen verticals will render, roughly how much of it, and what it
 six items in three groups design differently from six hundred. Run the vertical's reader:
 
 ```bash
-node <SKILL_ROOT>/templates/<vertical>/seed/read-site.mjs --site <siteId> [--limit <n>]
+node <templates>/<vertical>/seed/read-site.mjs --site <siteId> [--limit <n>]
 ```
 
 It prints one JSON: whether the vertical's app is installed, counts, one page of each entity

package/skills/wix-headless-kit/guides/reference-mode.md

@@ -1,7 +1,9 @@
 # Reference mode: a static site, or a server-rendered app in another language
 
 Read when SKILL.md step 1 resolves to a stack that cannot run `app/`. `<SKILL_ROOT>` is the
-installed skill folder; the shipped code is under `<SKILL_ROOT>/templates/`. Steps 2 to 5 of
+installed skill folder; the shipped code is in the folder `node <SKILL_ROOT>/install/templates.mjs`
+prints (the `wix-headless-templates` skill beside this one, or a copy fetched into
+`<SKILL_ROOT>/templates/`), and every `templates/…` path here is relative to it. Steps 2 to 5 of
 SKILL.md still apply; this file is the mechanics that differ.
 
 The data layer ships a second time as a **REST layer**: `templates/shared/rest/` (the auth seam
@@ -31,6 +33,12 @@ two transports: with `--plan` its REST twin and stores land in `js/wix/` beside
   to it. Seed per the vertical's `SEED.md` (Node + the CLI token, no project dependencies).
   Release with `npx @wix/cli@latest release` — no build. Item-page tags come from the entity's
   `seoData`, set after the fetch (`document.title`, the meta description).
+- **A dropped site on its Wix Dev Machine** (shape `static-in-astro`). The machine holds the
+  dropped pages in `public/` of an Astro starter with no pages of its own, and its Astro config
+  redirects `/` to `/index.html`. The pages stay where they are: run
+  `deploy.mjs <vertical> --stack static --out public`, which writes `public/js/wix/`, and wire the
+  pages in place as above. The config is left as it is, so the release goes through Astro:
+  `npx @wix/cli@latest build && npx @wix/cli@latest release`, to the same URL.
 - **Server-rendered, another language (Flask, Laravel, Rails, …).** The same shape as managed
   Astro — pages rendered on the server, the interactive surfaces in the browser — with hosting and
   SEO plumbing theirs. `init` still runs in the project folder; run `deploy.mjs <vertical> --stack