@wix/agent-skills 1.26.0 → 1.28.0

package/README.md

@@ -59,6 +59,7 @@ npx skills add wix/skills -g
 | [wix-design-system](skills/wix-design-system/SKILL.md) | Wix Design System reference      | Looking up WDS component props, examples, icons                                                                                     |
 | [wix-manage](skills/wix-manage/SKILL.md) | Wix business solution management | REST API operations for configuring and managing Wix business solutions                                                             |
 | [wix-headless-kit](skills/wix-headless-kit/SKILL.md) | Build and release a Wix Headless site on shipped, verified per-solution code | Building a new headless site for a business from a brief — store, bookings, blog, events, restaurants, members, donations and more — fast, with the integration code already written |
+| [wix-headless-templates](skills/wix-headless-templates/SKILL.md) | The shipped per-solution code wix-headless-kit builds from | Reading what a solution's data layer, hooks, pages and seed do, or seeding a site by hand; the kit fetches and deploys it for you |
 | [wix-headless](skills/wix-headless/SKILL.md) | Connect Wix business services to a headless frontend (SDK + Wix CLI), and optionally build & host the site | Setting up a Wix Headless backend or adding Wix business features (Stores, Bookings, CMS, Blog, Events, Forms, Members, Restaurants, Portfolio, Pricing Plans) — install apps, seed content, and produce an SDK-integration guide; for managed projects also scaffold a new site (create) or wire an existing design (connect), then build and release. Works across managed, self-managed, and stripe project types |
 | [wix-vibe-headless](skills/wix-vibe-headless/SKILL.md) | Connect an existing front end to Wix over client-only REST | Wiring a vibe-coded / HTML / Vite app to a live Wix site (storefront, bookings, blog, events, portfolio, restaurants, CMS, pricing plans) from the browser with a public `WIX_CLIENT_ID` — no SDK, no backend |
 | [wix-docs](skills/wix-docs/SKILL.md) | Look up the Wix API/SDK docs (shared fallback) | Confirming an exact Wix endpoint, method schema, field, or enum before writing code — `curl` doc-search + the `.md`-twin trick, or the Wix MCP tools. Referenced by the other skills as their docs-lookup fallback |

package/package.json

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

package/skills/wix-app/SKILL.md

@@ -24,7 +24,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 - [ ] **Step 2:** Read extension reference file(s) for the chosen type(s) and the project-wide [CODE_QUALITY.md](references/CODE_QUALITY.md)
   - [ ] **Dashboard page UI:** Translated the prompt into a workflow before choosing components — what the user must understand, focus on, investigate, act on, and see confirmed. See [UX Success Model](references/dashboard-page/UX_SUCCESS_MODEL.md), and the installed package's own `Collection Toolkit.md` guide for which component serves each need ([The Discovery Chain](references/WIX_PATTERNS_DOCS.md#the-discovery-chain)).
     - [ ] **No `SummaryBar` unless the request asked for one** — a named total, count, or "how many / how much" figure in the prompt. Not "the page seems like it wants one": an uninvited bar pushes the rows down and puts a number on screen nobody asked to be right about. When the request did ask, the number has to come from something that counts ([QUERY_AND_PAGING.md](references/dashboard-page/QUERY_AND_PAGING.md#what-fetchtotal-is-allowed-to-call)) and be read through `useSelector`, because the state is MobX ([TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md#reading-state-outside-the-table-it-is-mobx)).
-    - [ ] **A row the user can open, as a page** — `navigateToEntityPage` to an `EntityPage` when the record is editable, or to a read-only detail route when it isn't (the package's `Collection and Read-Only Detail Template`, reached from [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md)) — unless the prompt is explicitly a report or an export. **Never a `SidePanel`**: in Cairo that hosts a page's own panels. The template's page says why the read-only route is a WDS `Page` rather than an `EntityPage`.
+    - [ ] **A row the user can open, as a page — editable by default** — `navigateToEntityPage` to an `EntityPage` with a working form and save, for CMS and vertical SDK data alike; the three read-only cases are in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page). Unless the prompt is explicitly a report or an export. **Never a `SidePanel`**: in Cairo that hosts a page's own panels.
     - [ ] **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.
@@ -118,7 +118,7 @@ names the worked call, and `bundle` says whether props live in a `.d.ts` or in t
 table. Read the one artifact your open question needs. Resolve `<pkgRoot>` once per session
 ([Prerequisites](references/WIX_PATTERNS_DOCS.md#prerequisites)) and reuse it.
 
-**Add / edit / view one item from a collection is an `EntityPage`, not a dashboard modal** — see
+**Opening one item from a collection uses an editable `EntityPage` by default; create/edit flows also use `EntityPage`, never a dashboard modal** — see
 [Entity create and edit](#entity-create-and-edit), and `Collection to Entity Flow.md` in the
 package for the flow itself.
 
@@ -160,7 +160,9 @@ Compose from WDS layout primitives (`Box`, `Card`, `Text`). Do not add a third U
 
 ### Entity create and edit
 
-**Any dialog that creates, updates, or displays one record listed by a collection page is an `EntityPage` — not a Dashboard Modal.** This holds whether the records come from a CMS collection or an existing Wix app's SDK. A create / "add new" form is included: it **writes** the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading of this rule.
+**Opening a record listed by a collection page uses an editable `EntityPage` by default, whether the records come from CMS or a vertical SDK.** A request for a table or list is enough; the user does not need to ask for editing separately. The three read-only cases are in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page); a read-only detail page still opens as a route, never a Dashboard Modal or side panel.
+
+**Any create or edit form for a listed record is an `EntityPage`, not a Dashboard Modal.** A create / "add new" form is included: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading of this rule.
 
 A page that lists nothing — a settings page, an embedded-script config page — carries no `EntityPage` obligation. But "I built the list without `@wix/patterns`" is not an exception: a page that lists records should be a `CollectionPage`.
 
@@ -170,7 +172,7 @@ The documented flow:
 
 1. From the collection page's action cell or primary action, call `navigateToEntityPage({ path, entity })` from `usePatternsNavigate()`. (The patterns docs give this exact use case — "navigate to an entity page on an action cell click on a collection page" — and it renders the entity header immediately, before the fetch resolves.) On the **create** route there is no record to pass: omit `entity` and read the **Create route** section of `<pkgRoot>/dist/docs/useEntityPage.md`, which is what the whole "add new" flow turns on.
 2. Register the route with `PatternsReactRoute` inside `PatternsReactRouter`.
-3. In the entity page, `useEntityPage({ fetch, onSave })` owns fetching, saving, validation, dirty state, loading skeletons, and error states. Form state comes from `useForm` / `useController` in `@wix/patterns/form`. The call itself — both generics, what `onSave` receives, which params exist — is in `<pkgRoot>/dist/docs/useEntityPage.md`.
+3. Follow the selected template's entity hook: for SDK/API data, `useEntityPage({ fetch, onSave })` owns fetching, saving, validation, dirty state, loading skeletons, and error states; for CMS, the schema variant derives reads and writes from the source. Form state comes from `@wix/patterns/form`. Use the chosen template's documented signature, and wire saves to the real source rather than local state or a no-op.
 4. Compose the body from `EntityPage.Header`, `EntityPage.MainContent`, `EntityPage.AdditionalContent`, and `EntityPage.Card`. **WDS goes inside those cards** — `FormField`, `Input`, `Text` for the individual fields.
 
 Use a Dashboard Modal for dialogs that neither write nor display a listed record: a delete or discard confirmation, an unsaved-changes prompt, an informational notice, or any dialog on a page that lists nothing. Dialog size and field count are not exceptions — a one-field create form over a listed record is still an `EntityPage`. Reach for a modal because the interaction persists nothing, never because "the form should open in a modal."
@@ -415,7 +417,7 @@ Before moving to Step 5, re-open every page file you just wrote and check the ac
 
 - [ ] **The page has a `SummaryBar` only if the request asked for one.** Grep for it: an uninvited bar is a defect, not a bonus, and deleting it is the fix. If the request *did* ask, every metric earns its place and the headline counts what **matches the filters** (`state.collection.total`, fed by `fetchTotal`), not what has been paged in — any metric derived from `keyedItems` is labelled as such.
 - [ ] **If a `SummaryBar` number is fed by `fetchTotal`, follow that function to the call it makes and confirm the call counts.** A `fetchTotal` that resolves `undefined` — the usual cause being `pagingMetadata.total`, which a cursor-paged response does not carry — makes the bar report `0` beside a table full of rows, and it compiles, runs and passes every other check on this list. It must resolve a number from a count endpoint (`items.query(id)…count()`, a vertical's own count, or offset paging with `returnTotalCount: true`); if the API has none, delete `fetchTotal` and label the metric as loaded rows. See [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md#a-fetchtotal-that-resolves-undefined-shows-0-not-the-rows).
-- [ ] **Every row opens a page**: a `navigateToEntityPage` call literally appears in `onRowClick` — unless the prompt is explicitly a report or export-only view. A `SidePanel` in a collection page file is the defect this replaces; a display-only page routes to a read-only detail page, it does not fall back to a panel. `grep -n "<SidePanel" <page files>` should return nothing — match the JSX tag, not the bare word, or the templates' own "never a SidePanel" comments fail the check and invite someone to "fix" correct code.
+- [ ] **Every row opens an editable entity page by default**: `onRowClick` calls `navigateToEntityPage`, and the destination has an `EntityPage`, a working form, and a real save operation. A read-only route is justified by one of the three cases in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page), and the final response names which one; report-only/export-only requests need no drill-in. The save calls the source's real update method and lets a failed call throw, so the page shows its error — no no-op, local-state-only save, or `catch` that swallows the failure. If Preview is available, change one field, reload to confirm it saved, and change it back; otherwise report the save as unverified. A `SidePanel` in a collection page file is the defect this replaces. `grep -n "<SidePanel" <page files>` should return nothing — match the JSX tag, not the bare word, or the templates' own "never a SidePanel" comments fail the check and invite someone to "fix" correct code.
 - [ ] Every filter name declared in the toolbar also appears inside `fetchData`'s query construction — grep for the name in both places if unsure.
 - [ ] The table wires `errorState` — without it a failed query is indistinguishable from a slow one, and the page you just shipped cannot tell you which it is.
 - [ ] **Routed templates only (all but the settings one) — the entry file both passes and guards `location`.** `PatternsReactRouter` throws at open when `location` is missing *or* still `undefined` on the first render, and `tsc`, `wix build` and even a green build all pass regardless. Both halves are required — the `location={location}` prop **and** the `location ? … : null` guard around it, since `observeState` has not fired yet on the first render. Grep the entry file rather than trusting recall:
@@ -490,7 +492,7 @@ Execute these steps sequentially after all implementation is complete. See [APP_
 1. **Package Installation** — Detect package manager, run install
 2. **TypeScript Compilation** — `npx tsc --noEmit -p .`
 3. **Build** — `npx wix build`
-4. **Preview** — `npx wix preview`, in the foreground: it uploads, prints the preview URLs and exits on its own, so no `timeout`, backgrounding or `sleep`
+4. **Preview** — `npx wix preview`, in the foreground and unpiped: it uploads, prints the preview URLs and exits on its own, so no `timeout`, backgrounding, `sleep` or `| tail`. If your shell moves it to the background anyway, it stalled: read what it printed and `.wix/debug.log` once, then report that the preview did not complete. Don't poll, and don't promise a URL
 
 Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 

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

@@ -85,14 +85,18 @@ npx wix build
 
 ### Step 4: Preview Deployment
 
-`npx wix preview` is a one-shot command, not a server: it uploads a preview build, prints the preview URLs and **exits on its own**, in seconds. Run it in the foreground and read its output:
+`npx wix preview` is a one-shot command, not a server: it uploads a preview build, prints the preview URLs and **exits on its own**, in seconds. Run it in the foreground, exactly as written, and read its output:
 
 ```bash
 npx wix preview
 ```
 
+Don't pipe it (`| tail`, `| head`, `| grep`). The output is short, and a pipe holds back everything until the command exits, so a slow preview shows nothing at all.
+
 Don't wrap it in `timeout` (macOS has none, so the call fails before preview runs), background it, `sleep` or poll a log for it, or `kill` it afterwards. There is no process left to wait for or stop.
 
+**If it doesn't return:** your shell may move a long call to the background on its own (for example, after a 120s limit). That means the preview stalled, not that it's still working normally. Read the output it left and `.wix/debug.log` **once**. If neither has the preview URLs, report "preview did not complete" with whatever they show and stop validation. Don't sleep, poll, schedule a wake-up or start the preview again, and don't tell the user a URL is coming.
+
 **Success criteria:**
 - The command exits 0
 - It printed `✔ Preview created successfully!` and the preview URLs

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

@@ -66,7 +66,7 @@ See [Dashboard API Reference](dashboard-page/DASHBOARD_API.md) for all methods,
 
 Dashboard Pages cannot use `<Modal />`. For a true dialog overlay you **MUST** use a dashboard modal extension — never a React modal or the WDS `Modal` component. Reserve it for dialogs that neither write nor display a listed record (delete/discard confirmations, unsaved-changes prompts, notices), plus any dialog on a page that lists nothing (settings, config). They open via `dashboard.openModal()` — see [Dashboard Modal reference](DASHBOARD_MODAL.md).
 
-> **🛑 The test — does the dialog create, update, or display one record this page lists?** If yes, it is an `EntityPage`, not a modal — whether those records come from a CMS collection or an existing Wix app's SDK. **A create / "add new" form is included**: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading — the most common way the patterns-first rule gets dropped after the table is already correct.
+> **🛑 The test — does the dialog create, update, or display one record this page lists?** If yes, it is a route, not a modal — whether those records come from a CMS collection or an existing Wix app's SDK. **A create / "add new" form is included**: it writes the record, so it is an `EntityPage` even though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading — the most common way the patterns-first rule gets dropped after the table is already correct.
 >
 > The `EntityPage` comes from `@wix/patterns`, reached via `usePatternsNavigate().navigateToEntityPage`, with `useEntityPage` owning fetch/save/validation and `@wix/patterns/form` owning form state. Its route is registered with `PatternsReactRoute` inside `PatternsReactRouter` — so do not hand-roll page location state to fake a second view (`useState<PageLocation>` as a stand-in for a route); that is the router's job, and needing it is the signal you skipped one.
 >

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

@@ -15,7 +15,7 @@ Data owned by an existing Wix business app is read and written through that app'
 | pricing plans / subscriptions | `@wix/pricing-plans` |
 | bookings / services / staff / time slots | `@wix/bookings` |
 | calendar events / schedules | `@wix/calendar` |
-| table reservations | `@wix/table-reservations` |
+| table reservations | `@wix/table-reservations` (namespace `reservations`) — not `@wix/restaurants` |
 | restaurant menus / online orders | `@wix/restaurants` |
 | blog posts | `@wix/blog` |
 | site events / tickets / RSVPs | `@wix/events` |

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

@@ -21,10 +21,22 @@ for k, e in i.items():
 
 ## 2. Choose, then read the chosen template's page
 
-1. `Read <pkgRoot>/dist/docs/Page Templates.md` — which pages the request needs (read-only list, list with create/edit, settings only, or list with create/edit and settings) and where the rows come from (your own fetch, or a CMS collection).
+1. `Read <pkgRoot>/dist/docs/Page Templates.md` — choose the editable collection template by default, then account for the three read-only cases below, settings, and where the rows come from (your own fetch, or a CMS collection).
 2. `Read` the chosen template's page (`dist/docs/<entry file>`) — its files, and the wiring to keep. Most of that wiring passes `tsc` and `wix build` when wrong and fails only in the browser, which is why [Step 5's Preview](../../SKILL.md#validation) is not optional for a routed page.
 
-Take the smallest template that covers what the request names. A settings area or an edit form nobody asked for is not "more complete" — [Step 4c's checklist](../../SKILL.md#step-4c-ux-completeness-self-audit) does not ask for one.
+**Editing existing records is the default.** A site owner who opens a record from a dashboard table expects to fix what they see; a read-only page they never asked for sends them to a follow-up prompt. So every collection row opens an editable `EntityPage` with a working form and save operation, for CMS and SDK data alike. "Table", "list", "show" or "view" alone do not mean read-only. Apply this choice to each collection when a page contains several.
+
+Use the `Collection and Read-Only Detail Template` instead in exactly three cases:
+
+- **The user explicitly asks for read-only** — "view only", "do not allow changes".
+- **The source is verified to support no edits** — the schema or the documented update API leaves no editable field, or it is a CMS collection that can never be updated (owned by a Wix app other than Members and Forms, shared from another site, or without an update operation). Otherwise keep immutable fields read-only and edit the rest. When editing only needs setup (a permission, a role, an elevated backend call), keep the editable page and name the setup. Never ship a form whose save always fails, and never invent an update method or a no-op save handler to satisfy the default.
+- **The records are a log your app writes** — a backend event handler or job records something that happened elsewhere (a payment, a submission, an audit entry). Editing such a record falsifies history without changing what it describes, so it opens read-only unless the user asks to edit it.
+
+An explicit report-only or export-only request needs no detail page at all.
+
+An existing read-only page in the project shows how to call the data, not what to build; start from the template.
+
+Add create, delete or settings only when the workflow needs them; otherwise remove the template's create action and `/new` route. For a read-only CMS page, keep the schema-driven collection and adapt its detail route to the read-only layout rather than exposing the entity form.
 
 ## 3. Copy it into the extension
 

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

@@ -120,17 +120,16 @@ Presentation success applies across all five stages. Choose both the right **rep
 
 ### Choosing the Right Drill-In
 
-Choose the smallest interface that gives users enough context and room to complete the task. These are defaults, not rigid rules.
+Choose the interface that gives users enough context and room to complete the task. These are defaults, not rigid rules.
 
 | Interface | Use when… | Success looks like… |
 |---|---|---|
-| **Entity page** | The item is editable — the default for a business record. | Enough space and structure to complete deeper work. |
-| **Read-only detail page** | The collection is display-only. | Fully readable, linkable, one back-click from the list. |
+| **Entity page** | Default for opening a business record. | Editable fields, validation, and a save that persists. |
+| **Read-only detail page** | One of the [three read-only cases](DRAFT_TEMPLATE.md#2-choose-then-read-the-chosen-templates-page). | Linkable, one back-click from the list; the reason stated. |
 | **Modal** | A focused, bounded task that is not "open this record". | Attention stays on one task; the user returns cleanly. |
 | **Inline or expanded row** | A quick look *alongside* the drill-in, not instead of it. | Detail appears without a separate workspace. |
 
-Opening an item is a **route**, editable or not — a constraint, not a preference, and it outranks
-"smallest interface". A side panel is not one of the choices: in Cairo it hosts a page's own
+Opening an item is a **route**, editable or not — a constraint, not a preference. A side panel is not one of the choices: in Cairo it hosts a page's own
 panels. A display-only record still routes, just to a WDS `Page`, since `EntityPage` has no view
 mode.
 

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

@@ -4,13 +4,21 @@
 
 ```typescript
 if (v === 'V3_CATALOG') {
-  const product = await productsV3.getProduct(id);  // returns Product directly
+  const product = await productsV3.getProduct(id);  // returns V3Product directly
   return product;
 }
 const { product } = await products.getProduct(id);  // V1 wraps in { product }
 return product;
 ```
 
+The V3 entity type is `productsV3.V3Product`.
+
+---
+
+## Product page URL
+
+V3 `product.url` is populated only when the request's `fields` includes `'URL'` — `getProduct(id, { fields: ['URL'] })`, or the direct-call `searchProducts` / `queryProducts(query, { fields: ['URL'] })` (the fluent builder's `.find()` takes no options). V1 `productPageUrl` is an object, `{ base, path }`, not a string.
+
 ---
 
 ## Read product options and choices (V1 vs V3)

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

@@ -18,6 +18,8 @@ if (v === 'V3_CATALOG') {
 }
 ```
 
+V3 increments work only for inventory items with `trackQuantity: true`; the entries are `{ inventoryItemId, incrementBy }` with `incrementBy` 1 to 99999.
+
 To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
 
 ---

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

@@ -8,7 +8,7 @@ Both versions expose a fluent query builder, but the paging method differs:
 |--------|--------------------------------|----------------------------------|
 | API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
 | Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
-| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
+| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `productsV3.V3Product[]`) |
 | Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
 | `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
 | Next cursor | n/a | `res.cursors.next` (string) |
@@ -35,7 +35,7 @@ export async function listProductsPage(
   if (v === 'V3_CATALOG') {
     let builder = productsV3.queryProducts().limit(limit);
     if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
-    // Do NOT chain a sort — see OVERVIEW.md gotcha #10.
+    // Do NOT chain a sort — see [STORES_VERSIONING.md](../STORES_VERSIONING.md) gotcha #10.
     const res = await builder.find();
     return {
       products: res.items,

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

@@ -32,7 +32,7 @@ return product;
 
 ```typescript
 if (v === 'V3_CATALOG') {
-  // Signature: updateProduct(_id, productFields). Returns Product directly.
+  // Signature: updateProduct(_id, productFields). Returns V3Product directly.
   const current = await productsV3.getProduct(id);
   if (current.revision == null) throw new Error(`Product ${id} has no revision`);
   return await productsV3.updateProduct(id, {

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

@@ -21,8 +21,9 @@ doesn't express — or once the site exists and the work turns to managing or ex
 
 ## The model
 
-- **Shipped code is the implementation.** Every vertical ships under `templates/<vertical>/` in
-  the skill's repository, not in the skill folder: `node <SKILL_ROOT>/install/templates.mjs`
+- **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`
   fetches all of it once into `<SKILL_ROOT>/templates/` (a second) and prints the path; every
   script below fetches it itself when the folder is missing. The folder stays with the project
   (only the composed `project/` scaffolds are left out of its repository), so a later session
@@ -84,7 +85,7 @@ doesn't express — or once the site exists and the work turns to managing or ex
 
 ## The run
 
-Needed throughout: Node ≥ 20.11, git, a logged-in Wix CLI (`npx @wix/cli@latest whoami`;
+Needed throughout: Node ≥ 22.12 (Astro 7; the Wix CLI alone runs on 20.11), git, a logged-in Wix CLI (`npx @wix/cli@latest whoami`;
 `npx @wix/cli@latest login` is a device-code flow: surface the URL and code to the user, never
 read tokens into context), and the two companion skills installed beside this one, `wix-docs`
 and `wix-manage`. `node <SKILL_ROOT>/install/bootstrap.mjs` checks the CLI and runs the login
@@ -157,7 +158,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    |---|---|
    | supplies the content in any form: a CSV, JSON or spreadsheet, a list in the prompt, a PDF price list, a folder of photos and a text file, a link to their current catalog, anything that names the content | that IS the plan: map it into `plan.json` per `templates/shared/SUPPLIED-CONTENT.md` and the vertical's `SEED.md` ("Supplied content"), every entry, names and prices verbatim, their images and no others |
    | describes the content without listing it ("a store for hand-poured candles, four of them", "a dozen FAQ questions in three groups") | draft a plan from the description per the vertical's `SEED.md` (read only that for this; save `INSTRUCTIONS.md` for step 4) |
-   | says nothing about content ("build me a store") | on a site this run makes (create, adopt) draft a plan per the vertical's `SEED.md` so the site opens with content, and say in the closing message that it is placeholder content and where to replace it; on a site that existed before the run (attach, iterate, published-static, migrate) no plan and no seed: the site holds what the owner put there |
+   | says nothing about content ("build me a store") | on a site made for this run (create, adopt, config-only) draft a plan per the vertical's `SEED.md` so the site opens with content — demo content the agent decides on, without being asked — and say in the closing message that it is placeholder content and where the owner edits it. On a site that existed before the run: seed nothing; its content is its own |
 
    **An existing site has no plan of its own**: when the brief names a site by its id, or the
    folder's config does, the site holds the content already; the frontend reads what is there
@@ -184,21 +185,30 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    | nothing, or loose files (a CSV, a brief) | **empty** → create | `wix create` with the vertical's composed template, here; `--business-name` names the site | **yes**, from `--plan` |
    | 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 | no |
+   | 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, `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 |
 
-   **Setup seeds only a site it created in this run** (create and adopt: the site is empty by
-   construction, so the plan from step 2 goes in with the one call). A site that existed before
-   the run holds content the run did not make: read it first with the vertical's
-   `seed/read-site.mjs`, then, when the brief supplies or describes content, run the vertical's
-   seed module yourself with a plan (from the project root:
-   `node <SKILL_ROOT>/templates/<vertical>/seed/seed-<vertical>.mjs plan.json`). Seeds are
-   additive and idempotent by name; nothing on a site is ever deleted or overwritten.
+   **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
+   `SEED.md`, without being asked, so the site opens with something to see. Made for this run
+   means: setup created it (create, adopt), or the folder held only a `wix.config.json` and no
+   frontend (config-only — the config is what `init` leaves behind, and `init` always creates a
+   site; attach reports `siteOrigin: "init"`). A site that existed before the run — named by its
+   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`),
+   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
+   deleted or overwritten, and the result's `preexisting[]` names what was already there.
 
    - The brief names a site by id → not this call: read `<SKILL_ROOT>/guides/existing-site.md`
      and follow it (read the site, then `attach.mjs`, which does what setup does against the
-     site given; self-hosting and a project already on disk are in there too).
+     site given and seeds only with `--plan`, which that guide says to pass only for content the
+     brief supplies or asks to add; self-hosting and a project already on disk are in there too).
 
    `--vertical` is required and picks which shipped code deploys AND which seed runs. The
    `ready_for_brand_layer` event says `mode` (`create`, `adopt`, `migrate`, `published-static`),
@@ -267,7 +277,14 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    `https://manage.wix.com/dashboard/<siteId>` (the `siteId` of the `ready_for_brand_layer`
    event: on a migration preview that is the migrated site's dashboard, the release URL is the
    preview's, the original site is unchanged, and completing the migration is the user's next
-   step in the Wix CLI once they approve — say all three). **Copy the live URL verbatim from the
+   step in the Wix CLI once they approve — say all three). When the site takes money through
+   hosted checkout (a cart, a paid booking or rental, tickets, plans, donations) and nothing says
+   payments are already set up, say what a visitor meets at checkout until they are — "We
+   can't accept online payments. Contact us for help with your order." — and hand the two links
+   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
    `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
@@ -285,6 +302,10 @@ browser versus the server, the OAuth allow-list for a self-hosted origin, pre-re
 how to close such a run. A public site is still better served by managed Astro; say so when you
 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
+scripts make and the files beside this skill that carry the contracts.
+
 ## Verticals
 
 The shortlist. Match the brief against the first column; when it names a Wix product or a

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

@@ -1,7 +1,10 @@
 # An existing site: a new frontend for a site that already has its content
 
-Read when the brief names a Wix site by its id. Nothing here is seeded: the site owns its content
-and the frontend reads it live. (A project downloaded from Wix whose `.env.local` declares a
+Read when the brief names a Wix site by its id. That site existed before the run, so it owns its
+content and the frontend reads it live. Pass `--plan` only for content the brief **supplies or
+asks to add**; never draft demo content for it, however the brief describes the business (that
+is the create flow's job on a site made for the run — a folder holding only a `wix.config.json`
+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").
@@ -20,14 +23,18 @@ so on per the Verticals table); the brief picks among them. Then one determinist
 shape as setup (SKILL.md step 3):
 
 ```bash
-node <SKILL_ROOT>/install/attach.mjs --site <siteId> --business-name "<site name>" --vertical <vertical>[,<vertical>]
+node <SKILL_ROOT>/install/attach.mjs --site <siteId> --business-name "<site name>" --vertical <vertical>[,<vertical>] [--plan plan.json]
 ```
 
 `init`/`wix create` always create a site, so they are not used here. attach does what they do
 after creating one — the site's OAuth app, Wix hosting, `wix.config.json` — against the site
 given, copies the first vertical's composed template, deploys the rest, and starts the install
-detached. No seed runs and nothing on the site changes: the content is the site's own, read
-live through the deployed data layer. `attached` also says whether a frontend is already
+detached. With `--plan` the first vertical's seed runs with it, detached like setup's (sync on
+`.seed-exit` before release; `preexisting[]` in the result names what the site already held —
+nothing is deleted or overwritten). `--plan` also carries the plan's `capabilities` into the
+deploy. Without it nothing seeds and nothing on the site changes: the content is the site's own,
+read live through the deployed data layer. A vertical whose seed only installs an app (members:
+the Members Area, the profile layer) still needs that seed; attach says so in a `note`. `attached` also says whether a frontend is already
 serving at the site's address (`frontend.serving`, with the release date). When it is, a
 `wix release` from this project replaces it — the old deployment keeps its own address and
 production can be pointed back, but the user's site changes. Tell the user before you release,

package/skills/wix-headless-kit/guides/no-machine.md

@@ -0,0 +1,115 @@
+# No machine: the kit's run through the Wix APIs
+
+Read when you cannot run the commands this skill is built on: no shell, no file system, no Node, a
+sandbox that blocks the install, the CLI or the login, or a host that only talks to Wix through
+the Wix MCP. Nothing in this guide installs, downloads or runs anything. 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 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`). Installed beside this skill, or
+  fetched to `<SKILL_ROOT>/templates/`.
+- `<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.
+
+They install together and sit beside each other. When you are reading this skill online rather
+than from an install, the others are published alongside it, by those names, and each skill's
+manifest lists its files. Read each file in full: a fetch tool that summarizes drops the exact
+calls and shapes; a tool that returns the file's text, or one that runs code and can fetch a URL,
+does not.
+
+Two things such a run does not produce, and never claims: a frontend built from the shipped `app/`
+code (that needs a build), and a release of one. Everything else the kit does to a site, it does
+through calls you can make.
+
+## 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.
+
+## 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). Read `SEED.md`, 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. Image prompts
+need the Media Manager; without it, products and services stay text-only, say so.
+
+## 5. The frontend
+
+The shipped `app/` code cannot be built here, and the Astro pages cannot be released. A page can
+still be shipped: one self-contained `index.html` that loads the Wix SDK from a package CDN and
+talks to the site as a visitor, dropped onto the site from step 2 through
+`<MANAGE>/references/sites/upload-static-site.md`. The kit's own frontend for this site is a run
+with a machine, which attaches to this site (`guides/existing-site.md`) rather than making a new one.
+
+**The page.** One file, a few hundred lines, written in full before the first drop: the drop takes
+the complete file set in one call, and a response has a hard size limit, so there is no second
+pass. 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.** Take every SDK call's 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. 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.
+
+**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 run here, so a wrong shape fails
+silently in the browser; the file beside the skill is the check that is available.
+
+## 6. Closing
+
+As in SKILL.md step 5, minus the live URL when nothing was released: what exists on the site, by
+name; the dashboard link `https://manage.wix.com/dashboard/<metaSiteId>` and each solution's own
+pages from its INSTRUCTIONS.md table; what is placeholder; payments, when the site takes money;
+and what this run could not do, with the site id, so a run with a machine continues here.