@wix/agent-skills 1.26.0 → 1.27.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.27.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:

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/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-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

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/install/attach.mjs

@@ -2,12 +2,18 @@
 // exists (named in the prompt by its id). `init`/`wix create` cannot do this: they always create
 // a site. This script does what they do AFTER creating one — OAuth app, managed hosting, env
 // vars, `wix.config.json` — against the site id given, then scaffolds and deploys like
-// setup.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+// setup.mjs. Nothing on the site is changed or deleted. Seeding is the caller's decision: with
+// --plan the first vertical's seed runs with it (additive, idempotent by name; what the site already
+// held comes back as preexisting[]); without one nothing is seeded — the site owns its content.
 //
 //   node <SKILL_ROOT>/install/attach.mjs [--site <metaSiteId>] --business-name "<Brand>" \
-//        --vertical <a>[,<b>…] [--stack astro|react|lib|static] [--hosting wix|self [--origin <url>[,<url>]]] \
+//        --vertical <a>[,<b>…] [--plan plan.json] [--stack astro|react|lib|static] [--hosting wix|self [--origin <url>[,<url>]]] \
 //        [--subfolder [--folder-name <name>]]
 //
+// --plan           the content to seed, per the vertical's SEED.md — given when the brief supplies or
+//                  describes content (SKILL.md step 2). Also carries plan.capabilities (mediaUpload,
+//                  siteSearch) into deploy. Without it: no seed, and no capabilities.
+//
 // --hosting        wix (default): the frontend releases to Wix hosting — the site's app project is
 //                  created or reused and `wix release` uploads to its *.wix-site-host.com address.
 //                  self: the frontend is hosted elsewhere (Vercel, a Flask server, …): no app
@@ -19,8 +25,8 @@
 // --site           the site. May be omitted when the folder holds a wix.config.json: then it is
 //                  the site in that config (what `init` left behind in an empty folder).
 // --business-name  the site's name (names the folder, the hosting slug and the app project).
-// --vertical       which shipped code deploys (no seed runs — the site owns its content). Both are
-//                  the caller's decision, read off the site before calling this (SKILL.md step 3).
+// --vertical       which shipped code deploys, and whose seed runs with --plan (the first one). Both
+//                  are the caller's decision, read off the site before calling this (SKILL.md step 3).
 // --stack          astro (default) in a folder without a project: copies the first vertical's
 //                  composed template (templates/<vertical>/project). react|static there: writes wix.config.json
 //                  and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md. In a folder
@@ -41,7 +47,7 @@
 // ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@latest whoami`)
 // whose account owns or co-manages the site.
 import { spawn, spawnSync, execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
@@ -69,6 +75,8 @@ const flag = (name) => {
   return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
 };
 const stackFlag = flag("stack");
+const planPath = flag("plan");
+if (planPath && !existsSync(resolve(planPath))) fail("args", `--plan ${planPath}: no such file`);
 const hosting0 = flag("hosting") ?? "wix";
 const origins = (flag("origin") ?? "").split(",").map((o) => o.trim().replace(/\/$/, "")).filter(Boolean);
 const subfolder = argv.includes("--subfolder");
@@ -90,6 +98,10 @@ if (cwdConfig) {
   }
 }
 const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
+// Where the site came from decides the seed (SKILL.md step 3). A config in this folder for this site
+// is what `init` leaves behind, and `init` always creates a site: that site was made for this run and
+// is empty. A site named with --site (and not already this folder's) existed before the run.
+const siteOrigin = cwdConfig && (cwdConfig.siteId === siteId || cwdConfig.projectId === siteId) ? "init" : "given";
 const stack = stackFlag ?? "astro";
 const knownVerticals = listVerticals(TEMPLATES);
 const verticals = argv
@@ -119,7 +131,7 @@ if (!subfolder) {
   }
 }
 const mode = !subfolder && hasProject ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
-emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null });
+emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null, siteOrigin });
 
 // ---- http ---------------------------------------------------------------------------------------
 const cliToken = (site) => {
@@ -289,7 +301,8 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 
 if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
   emit("ready", { projectDir, siteId, appId, baseUrl, hosting, frontend, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
-    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack} (the client id is read from wix.config.json); no seed — the site owns its content` +
+    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack}${planPath ? ` --plan ${planPath}` : ""} (the client id is read from wix.config.json); ` +
+      (planPath ? `then seed with the plan: node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
       (hosting === "self" ? `; you host it: origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}` : "") });
   process.exit(0);
 }
@@ -297,7 +310,7 @@ if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
 // ---- 3 · deploy shipped code + deps (adds nothing to a scaffold from the template) --------------
 let deployResult = {};
 {
-  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
+  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(planPath ? ["--plan", resolve(planPath)] : [])], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
   if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
   try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going */ }
   if (deployResult.error) fail("deploy", deployResult.error);
@@ -315,6 +328,32 @@ if (existsSync(join(projectDir, "package.json"))) {
   emit("install_started", install);
 }
 
+// ---- 5 · the seed, detached, only with --plan ------------------------------------------------------
+// The site existed before this run, so content goes in only when the caller says so (the brief
+// supplied or described it). Same shape as setup: result JSON + exit marker, synced on before release.
+// Seeds are additive and idempotent by name; what the site already held is reported, never touched.
+let seed = null;
+if (planPath) {
+  const seedDir = join(TEMPLATES, verticals[0], "seed");
+  const seedName = existsSync(seedDir) ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs")) : undefined;
+  if (!seedName) fail("seed", `no seed module found under ${seedDir}`);
+  const seedChild = spawn(
+    "sh",
+    ["-c", `node "${join(seedDir, seedName)}" "${resolve(planPath)}" > seed-result.json 2> seed.log; echo $? > .seed-exit`],
+    { cwd: projectDir, detached: true, stdio: "ignore" },
+  );
+  seedChild.unref();
+  seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
+  emit("seeding_started", { vertical: verticals[0], ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${verticals[0]}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
+} else {
+  if (siteOrigin === "init") {
+    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per templates/${verticals[0]}/seed/SEED.md — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
+  }
+  if (verticals.includes("members")) {
+    emit("note", { step: "seed", detail: "members: the Members Area app (the profile layer, no content) is installed by templates/members/seed/seed-members.mjs — run it unless the site already has the app" });
+  }
+}
+
 // ---- done ----------------------------------------------------------------------------------------
 emit("ready_for_brand_layer", {
   projectDir,
@@ -330,9 +369,15 @@ emit("ready_for_brand_layer", {
   mode,
   stack,
   install,
-  seed: null,
+  seed,
+  siteOrigin,
   next:
-    "the site's content is live already — nothing to seed; get the measure of the site (SKILL.md step 3), theme + write the pages" +
+    (seed
+      ? "the plan is seeding in the background (additive; the result's preexisting[] names what the site already held) — sync on .seed-exit before release; "
+      : siteOrigin === "init"
+        ? "no plan given and this site was made for this run (empty): draft a plan per SEED.md and run the vertical's seed before release; "
+        : "no plan given, so nothing seeds — the site existed before this run and its content is its own; ") +
+    "get the measure of the site (SKILL.md step 3), theme + write the pages" +
     (mode === "link" && hosting !== "self" ? "; make the project what its stack needs on Wix hosting (SKILL.md step 1)" : "") +
     (install ? "; wait for the install marker" : "") +
     (hosting === "self"

package/skills/wix-headless-kit/install/check.mjs

@@ -5,7 +5,7 @@
 //   node <SKILL_ROOT>/install/check.mjs
 //
 // Two layers, two answers:
-//   skill      the installed skill folder (SKILL.md, guides/, install/, cold-start/) against the
+//   skill      the installed skill folder (SKILL.md, guides/, install/) against the
 //              repository head: `current`, `behind` (with the files that differ), or `unknown`.
 //   templates  `templates/.source` commit against the head: `current` or `behind`, with the
 //              verticals touched and the commit messages in between.
@@ -15,7 +15,7 @@ import { mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
-import { SKILL_ROOT, installSource, templatesDir, templatesSource } from "./templates.mjs";
+import { SKILL_ROOT, TEMPLATES_PATH, installSource, templatesDir, templatesSource } from "./templates.mjs";
 
 const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 120_000, ...opts });
 const skillName = SKILL_ROOT.split("/").pop();
@@ -64,11 +64,11 @@ if (dir) {
   else if (src.commit === head) out.templates = { status: "current", commit: src.commit };
   else {
     out.templates = { status: "behind", commit: src.commit, head };
-    const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
-    const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
+    const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);
+    const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);
     if (files.length || log.length) {
       out.templates.commitsBehind = log.length;
-      out.templates.verticals = [...new Set(files.map((f) => f.split("/")[1]).filter((v) => v && !v.endsWith(".mjs")))].sort();
+      out.templates.verticals = [...new Set(files.map((f) => f.split("/")[2]).filter((v) => v && !v.endsWith(".mjs") && !v.endsWith(".md")))].sort();
       out.templates.commits = log.slice(0, 20);
     } else {
       out.templates.detail = git(["-C", tmp, "cat-file", "-e", src.commit]).status === 0 ? "no template changes between the two commits" : "the recorded commit is not in the repository's history (a branch that was deleted?)";

package/skills/wix-headless-kit/install/deploy.mjs

@@ -80,6 +80,8 @@ const CAPABILITY_DEPS = {
   "media-upload": {
     "@wix/media": "^1.0.271",
     "@wix/essentials": "^1.0.10",
+    // the endpoint reads the caller's own session for a members policy
+    "@wix/members": "^1.0.511",
   },
   "site-search": {
     "@wix/search": "^1.0.90",
@@ -297,7 +299,8 @@ if (stack === "static") {
       // Every vertical has a types.ts; flat in one folder they would collide, so each lands as
       // <vertical>-types.ts and the vertical's own files are pointed at it below.
       if (f === "types.ts") cpSync(join(appWix, f), join(JS, `${vertical}-types.ts`), COPY);
-      else if (f.endsWith("-core.ts") || f.endsWith("-store.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
+      // *.generated.ts: data a core file imports (the forms' per-country address templates).
+      else if (f.endsWith("-core.ts") || f.endsWith("-store.ts") || f.endsWith(".generated.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
     }
     const own = new Set([...readdirSync(join(root, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
     for (const f of own) {
@@ -362,9 +365,10 @@ for (const policy of uploadPolicies) {
     !Array.isArray(policy.accept) ||
     !policy.accept.every((mime) => typeof mime === "string") ||
     !Number.isSafeInteger(policy.maxBytes) ||
-    policy.maxBytes < 1
+    policy.maxBytes < 1 ||
+    (policy.audience !== undefined && policy.audience !== "members" && policy.audience !== "visitors")
   ) {
-    console.log(JSON.stringify({ error: "each mediaUpload policy needs id, accept: string[], and positive integer maxBytes" }));
+    console.log(JSON.stringify({ error: 'each mediaUpload policy needs id, accept: string[], positive integer maxBytes, and optionally audience: "members" (default) | "visitors"' }));
     process.exit(1);
   }
 }

package/skills/wix-headless-kit/install/templates.mjs

@@ -1,13 +1,15 @@
-// Where the shipped code is. The verticals live in the skill's repository under `templates/`
-// (each with its code layers, its tools and a composed project with a lockfile), not in the skill
-// folder: the skill stays small and the code is fetched once, when first needed.
+// Where the shipped code is. The verticals live in the skill's repository as a skill of their own,
+// `skills/wix-headless-templates/` (each with its code layers, its tools and a composed project
+// with a lockfile), not in this skill's folder: this skill stays small and the code is fetched
+// once, when first needed.
 //
 //   node <SKILL_ROOT>/install/templates.mjs [--refresh]      # prints {templates, source, verticals}
 //
 // Resolution, in order:
-//   1. a checkout of the repository itself (the skill folder sits in it): `<repo>/templates/`.
+//   1. the sibling skill folder, `<SKILL_ROOT>/../wix-headless-templates/`: a checkout of the repository,
+//      or a plugin install that carries both skills (every plugin manifest lists the templates skill).
 //   2. the cache `<SKILL_ROOT>/templates/`, filled by an earlier call (`--refresh` refetches).
-//   3. a fetch: a sparse, shallow clone of `templates/` from the repository the skill was installed
+//   3. a fetch: a sparse, shallow clone of `skills/wix-headless-templates/` from the repository the skill was installed
 //      from (skills-lock.json's `source`, default wix/skills), at the branch or tag the install
 //      named (its `ref`, falling back to the default branch when that ref no longer exists) or the
 //      repository's default branch. The lock records no commit, so there is nothing more exact to
@@ -25,6 +27,8 @@ import { fileURLToPath } from "node:url";
 
 export const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 export const DEFAULT_REPO = "https://github.com/wix/skills.git";
+/** The templates skill's folder in the repository. */
+export const TEMPLATES_PATH = "skills/wix-headless-templates";
 
 const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 180_000, ...opts });
 
@@ -68,7 +72,7 @@ export function listVerticals(dir) {
 }
 
 export function templatesDir({ refresh = false, need = null } = {}) {
-  const checkout = resolve(SKILL_ROOT, "..", "..", "templates");
+  const checkout = resolve(SKILL_ROOT, "..", "wix-headless-templates");
   if (existsSync(join(checkout, "shared", "app"))) return checkout;
   const cache = join(SKILL_ROOT, "templates");
   if (!refresh && existsSync(join(cache, "shared", "app"))) {
@@ -90,12 +94,12 @@ function fetchIgnoredPart(cache, need) {
   const { repo } = installSource();
   const r = cloneSparse(src.repo ?? repo, src.commit ?? process.env.WIX_HEADLESS_FAST_TEMPLATES_REF ?? null);
   const tmp = r.tmp;
-  if (r.status !== 0 || !existsSync(join(tmp, "templates", need))) {
+  if (r.status !== 0 || !existsSync(join(tmp, TEMPLATES_PATH, need))) {
     rmSync(tmp, { recursive: true, force: true });
-    throw new Error(`could not fetch templates/${need} from ${src.repo ?? repo}${src.commit ? ` @ ${src.commit.slice(0, 7)}` : ""}: ${(r.stderr || r.stdout || "not in the clone").trim().slice(-300)}`);
+    throw new Error(`could not fetch ${TEMPLATES_PATH}/${need} from ${src.repo ?? repo}${src.commit ? ` @ ${src.commit.slice(0, 7)}` : ""}: ${(r.stderr || r.stdout || "not in the clone").trim().slice(-300)}`);
   }
-  for (const part of ["blank", ...readdirSync(join(tmp, "templates"), { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(tmp, "templates", d.name, "project"))).map((d) => `${d.name}/project`)]) {
-    const from = join(tmp, "templates", part);
+  for (const part of ["blank", ...readdirSync(join(tmp, TEMPLATES_PATH), { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(tmp, TEMPLATES_PATH, d.name, "project"))).map((d) => `${d.name}/project`)]) {
+    const from = join(tmp, TEMPLATES_PATH, part);
     if (existsSync(from) && !existsSync(join(cache, part))) cpSync(from, join(cache, part), { recursive: true });
   }
   rmSync(tmp, { recursive: true, force: true });
@@ -126,33 +130,33 @@ function fetchTemplates(cache) {
     rmSync(tmp, { recursive: true, force: true });
     throw new Error("git is not installed or not on PATH; the shipped code is fetched with a git clone of the skill's repository");
   }
-  if (r.status !== 0 || !existsSync(join(tmp, "templates", "shared", "app"))) {
+  if (r.status !== 0 || !existsSync(join(tmp, TEMPLATES_PATH, "shared", "app"))) {
     rmSync(tmp, { recursive: true, force: true });
-    throw new Error(`could not fetch templates/ from ${repo}${ref ? ` @ ${ref}` : ""}: ${(r.stderr || r.stdout || "no templates/shared/app in the clone").trim().slice(-400)}`);
+    throw new Error(`could not fetch ${TEMPLATES_PATH}/ from ${repo}${ref ? ` @ ${ref}` : ""}: ${(r.stderr || r.stdout || `no ${TEMPLATES_PATH}/shared/app in the clone`).trim().slice(-400)}`);
   }
   const commit = git(["-C", tmp, "rev-parse", "HEAD"]).stdout.trim();
   rmSync(cache, { recursive: true, force: true });
   mkdirSync(dirname(cache), { recursive: true });
-  try { renameSync(join(tmp, "templates"), cache); }
-  catch { cpSync(join(tmp, "templates"), cache, { recursive: true }); }
+  try { renameSync(join(tmp, TEMPLATES_PATH), cache); }
+  catch { cpSync(join(tmp, TEMPLATES_PATH), cache, { recursive: true }); }
   rmSync(tmp, { recursive: true, force: true });
   writeFileSync(join(cache, ".gitignore"), IGNORED.join("\n") + "\n");
   writeFileSync(join(cache, ".source"), JSON.stringify({ repo, ref: ref ?? (fellBack ? `default branch (${lockRef} not found)` : "default branch"), commit, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
 }
 
-// A sparse, shallow clone of templates/ at a ref (branch, tag, or commit id) into a temp dir.
+// A sparse, shallow clone of the templates skill's folder at a ref (branch, tag, or commit id) into a temp dir.
 function cloneSparse(repo, ref) {
   const tmp = mkdtempSync(join(tmpdir(), "wix-headless-kit-templates-"));
   let r;
   if (ref && /^[0-9a-f]{40}$/i.test(ref)) {
     // a commit: shallow-fetch just it (GitHub serves any reachable commit by id)
-    for (const args of [["init", "-q", tmp], ["-C", tmp, "remote", "add", "origin", repo], ["-C", tmp, "fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", ref], ["-C", tmp, "sparse-checkout", "set", "templates"], ["-C", tmp, "checkout", "-q", "FETCH_HEAD"]]) {
+    for (const args of [["init", "-q", tmp], ["-C", tmp, "remote", "add", "origin", repo], ["-C", tmp, "fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", ref], ["-C", tmp, "sparse-checkout", "set", TEMPLATES_PATH], ["-C", tmp, "checkout", "-q", "FETCH_HEAD"]]) {
       r = git(args);
       if (r.status !== 0) break;
     }
   } else {
     r = git(["clone", "--quiet", "--depth", "1", "--filter=blob:none", "--sparse", ...(ref ? ["-b", ref] : []), repo, tmp]);
-    if (r.status === 0) r = git(["-C", tmp, "sparse-checkout", "set", "templates"]);
+    if (r.status === 0) r = git(["-C", tmp, "sparse-checkout", "set", TEMPLATES_PATH]);
   }
   return { ...r, tmp };
 }