@wix/agent-skills 1.31.0 → 1.31.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.31.0",
+  "version": "1.31.2",
   "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/STORES_VERSIONING.md

@@ -130,4 +130,4 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 - [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
 - [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.
+For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsMethodSchema` (use `ReadFullDocsArticle` only for prose). Always return the required permission scopes to the user.

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,11 +101,16 @@ 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.
 
+Throughout any run, keep the site working at every step so the user can try it as it grows. Steps
+only the site owner can take never hold a flow back: drafted content is live, and anything that
+takes money reaches Wix's checkout before payments are connected. The owner's steps go in the
+closing with their links, as next steps the user can take or ask for.
+
 Throughout any run: if the user asks to send feedback to Wix, complains or gets frustrated, or the
 run hits friction of any kind: anything that cost more turns than it should have, whether or not
 it ended in an error (a confusing error, a doc gap, a seed that had to be re-run, a shipped file
@@ -142,8 +148,9 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
      `astro.config.mjs` `integrations: [wix(), react()]`, `adapter: wixHostingAdapter()`,
      `output: "server"`, `security: { checkOrigin: false }`, `image.domains` with
      `static.wixstatic.com`. An Astro project made without the CLI has none of that; add it
-     before deploying, and the site serves every route. The integration supports **Astro 5**: a
-     project on another major is pinned to 5 first, or connected as a React host.
+     before deploying, and the site serves every route. The integration's current major
+     (`@wix/astro` 3, as in this skill's templates) requires **Astro 7**: a project on an earlier
+     major moves to 7 first, or is connected as a React host.
    - **React and other bundlers** release their own build as files. So routes are hash routes,
      or one emitted HTML file per route linked by its file name — decided before the first route
      is written; any URL handed to Wix as a return target must be one the host serves. Verify by
@@ -166,9 +173,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.
@@ -188,9 +195,13 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    | a frontend, no config (a `package.json`, or `index.html` at the root: someone's Astro, Vite, Next, plain HTML) | **project** → adopt | `init` in place gives it a new, empty site, then deploys; `--stack` from step 1 is required; make the project what that stack needs on Wix hosting (step 1) before or right after | **yes**, from `--plan` |
    | 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 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 install, `node <SKILL_ROOT>/install/install.mjs` (nothing when `node_modules` already satisfies the lock); 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 and the CLI's blank Astro starter with no work of its own (`wix-astro-blank`, only the blank template's packages: a Dev Machine's never-released site, a bare `wix create`) | **blank-starter** → refuses | `attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json]` on the config's site: the vertical's composed template takes the starter's place (its lockfile with it), the install and the seed start detached; build the brand layer while they run | **yes**, from `--plan`: the site was made for this run and is empty, unless `read-site.mjs` shows content |
    | 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 |
 
+   A folder no row names is **wix-project**: the fill-only path — never scaffold, `init`, reseed or delete; deploy, edit, release. A wrong guess costs a slower run, never the user's work.
+
    **Who decides the seed: where the site came from, never the brief's wording.** A site made
    for this run is empty by construction, so it is always seeded — with the brief's content when
    it supplies or describes any, otherwise with demo content the agent drafts per the vertical's
@@ -201,7 +212,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
@@ -229,7 +241,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    It emits one JSON event per line and returns in **~35s**: **scaffolds** the project from the
    vertical's composed template (`wix create` copies it: the code and its lockfile arrive with
    the scaffold), **deploys** whatever the folder still lacks (patching `package.json` with every
-   dependency the code imports), then **starts two detached background jobs** — the dependency install (`npm ci --ignore-scripts || npm install --ignore-scripts`)
+   dependency the code imports), then **starts two detached background jobs** — the dependency install (`install/install.mjs`: nothing when `node_modules` already satisfies the lock, `npm install --ignore-scripts` over a tree that is there, else `npm ci --ignore-scripts || npm install --ignore-scripts`)
    and the **seed** — whose logs and completion markers are in the events. The final
    `ready_for_brand_layer` event carries the project dir, siteId, ready-made dashboard links,
    and both markers. Relay notable events. On an `error` event, recover just that step via the
@@ -237,8 +249,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
 
    **Recovering one step, or adding a solution later:** the pieces run on their own from the
    project root — `node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack <stack>` (the client
-   id is read from `wix.config.json`), ONE `npm ci --ignore-scripts || npm install
-   --ignore-scripts` (**never a second npm install concurrently**: two npms in one
+   id is read from `wix.config.json`), ONE `node <SKILL_ROOT>/install/install.mjs`
+   (**never a second npm install concurrently**: two npms in one
    `node_modules` race and redo each other's work; setup already started one — wait on its
    marker), the vertical's seed module per its `seed/SEED.md`.
    A code change on an existing project is done when it is **released** (step 5) and the live
@@ -254,11 +266,16 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    `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.
+   **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.
 5. **When both background jobs have completed** — the install's marker
-   (`node_modules/.package-lock.json`) and the seed's (`.seed-exit`) both exist — **verify the
+   (`.install-exit`, containing `0`) and the seed's (`.seed-exit`) both exist — **verify the
    seed succeeded** (`.seed-exit` contains `0`; `seed-result.json` has the created counts for
    your summary — if non-zero, read `seed.log` and re-run the seed module manually). Those two
    seed files exist **only when setup started the seed** (attach runs none: only the install