@wix/agent-skills 1.22.0 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.22.0",
+  "version": "1.23.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

@@ -28,8 +28,8 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
     - [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
 
     A filtered table with no drill-in and no working filters is what gets built when nobody states the requirement — the most common way a generated dashboard disappoints. The aggregate is the judgment call; the drill-in and the filters are not.
-  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Identified which case in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) — A (collection only), B (collection + entity), C (settings only), or D (all three) — matches what Step 2's workflow analysis above just established — then copied and adapted that case's files. Composing the page shell, provider nesting, or router wiring from scratch when a case already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the matching case's files don't cover, not a replacement for starting there.
-  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls) and `dist/dts-bundle/` (types) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
+  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Identified which case in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) — A (collection only), B (collection + entity), C (settings only), or D (all three) — matches what Step 2's workflow analysis above just established — then copied and adapted that case's files. Composing the page shell, provider nesting, or router wiring from scratch when a case already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the matching case's files don't cover, not a replacement for starting there. The reverse holds too: a case replaces composing the shell, never the discovery chain, so every symbol the case doesn't show still goes through the next gate.
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. Then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls) and `dist/dts-bundle/` (types) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
   - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the index** which single artifact answers the question you actually have — `importPath`, `examples`, or `bundle` — and read only that one, per [Component Selection Order](#component-selection-order)'s "the short version". State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an `importPath` the index already gave you, is the failure this gate exists to prevent.
 
     For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
@@ -226,6 +226,14 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 
 Find the entity the user mentioned in the [entity → SDK module map](references/SDK_MODULE_MAP.md) and use that package. If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
 
+**SDK types:** access them through the namespace you import, as `<namespace>.<TypeName>`, using any type name shown in the docs — never import a type by name from the `@wix/<pkg>` root.
+
+```ts
+import { orders } from '@wix/ecom';
+const rows: orders.Order[] = [];              // ✅
+// import type { Order } from '@wix/ecom';    // ❌ has no exported member 'Order'
+```
+
 ---
 
 ## Data Collection Inference
@@ -440,7 +448,7 @@ Only after validation passes, provide a **concise summary section** at the top o
 - ✅ Dependencies: [Installed / status message]
 - ✅ TypeScript: [No compilation errors / status]
 - ✅ Build: [Completed successfully / status]
-- ✅/⚠️ Preview: [Running at URL / Failed - reason]
+- ✅/⚠️ Preview: [Created — Dashboard URL / Failed - reason]
 
 **⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)
 ```
@@ -480,7 +488,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`
+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`
 
 Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 

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

@@ -85,23 +85,29 @@ npx wix build
 
 ### Step 4: Preview Deployment
 
-Start the preview server:
+`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:
 
 ```bash
 npx wix preview
 ```
 
+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.
+
 **Success criteria:**
-- Preview server starts successfully
-- Preview URLs are generated (both site and dashboard)
+- The command exits 0
+- It printed `✔ Preview created successfully!` and the preview URLs
+
+**URL extraction:** the URLs follow `Open the preview on:`, one per line, each in parentheses:
 
-**URL extraction:** Parse the terminal output to find both preview URLs. Look for patterns like:
-- Site preview: `Site preview: https://...` or `Site URL: https://...`
-- Dashboard preview: `Dashboard preview: https://...` or `Preview URL: https://...` or `Your app is available at: https://...`
+```
+  › Site (https://www.wix.com/app-installer?appId=...)
+  › Editor (https://www.wix.com/app-installer?appId=...)
+  › Dashboard (https://www.wix.com/app-installer?appId=...)
+```
 
-Extract both URLs and provide them to the user for manual verification.
+A long URL wraps across several lines. Join the lines up to the closing `)` before using it. Give the Site and Dashboard URLs to the user for manual verification.
 
-**On failure:** Report the preview startup errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
+**On failure:** Report the preview errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
 
 ## Validation Report
 
@@ -111,7 +117,7 @@ After completing all steps, provide a summary:
 - Dependencies: ✓ All packages installed successfully
 - TypeScript: ✓ No compilation errors
 - Build: ✓ Compiled successfully
-- Preview: ✓ Running at [URL]
+- Preview: ✓ Created — [Dashboard URL]
 
 **Fail:**
 - Identify which step failed
@@ -138,7 +144,7 @@ Read: .wix/debug.log (with offset to the end)
 | Package installation fails | Missing lock file, network issues, or corrupted node_modules | Delete `node_modules` and lock file, then reinstall |
 | TypeScript compilation fails | Type mismatches, missing declarations, or incorrect types | Fix TypeScript errors shown in `npx tsc --noEmit -p .` output |
 | Build fails | TypeScript errors, missing dependencies, or internal CLI error | Fix TypeScript errors in source; for non-obvious failures, check `.wix/debug.log` |
-| Preview fails to start | Port conflict, config issue, or internal CLI error | Check `wix.config.json`; if unclear, check `.wix/debug.log` for details |
+| Preview fails | Config issue, not logged in, or internal CLI error | Check `wix.config.json`; if unclear, check `.wix/debug.log` for details |
 | Console errors in preview | Runtime exceptions | Check browser console output |
 | UI not rendering | Component errors | Review component code and imports |
 | CLI error with no clear message | Truncated terminal output | Read `.wix/debug.log` for the full error trace and stack details |

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

@@ -41,4 +41,6 @@ Data owned by an existing Wix business app is read and written through that app'
 | locations / site properties | `@wix/business-tools` |
 | app instances | `@wix/app-management` |
 
+Types from these packages are accessed as `<namespace>.<TypeName>` — see [SDK types](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms).
+
 If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.

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

@@ -1,6 +1,6 @@
 # Draft Template — the starting point for every dashboard page
 
-**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file for [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md), the package's own `Collection Toolkit.md` guide, [TABLE_STATE.md](TABLE_STATE.md), a component doc, or an MCP lookup when the request needs something no case shows.
+**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file when the request needs something no case shows, and then go to [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md) first — before any lookup inside `node_modules/@wix/patterns`, `index.json` included. It routes you to the package's own `Collection Toolkit.md` guide, a component doc or an example; [TABLE_STATE.md](TABLE_STATE.md) and MCP lookups come after it.
 
 Every snippet below was copied from the installed `dist/docs/*.md` and `dist/dts-bundle/*.d.ts`, not from memory — confirm props against your own installed version before deviating.
 

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

@@ -1,6 +1,6 @@
 ---
 name: wix-headless-fast
-description: "Build a Wix Headless site fast by wiring SHIPPED, verified @wix/sdk code instead of authoring the integration from recipes. Each Wix business vertical ships a typed, framework-agnostic React core (data layer returning plain DTOs, hooks, headless components) plus an Astro overlay (SSR pages with owner-editable SEO pre-wired) and a build-time REST seed script — the agent scaffolds via the Wix CLI, deploys the shipped code, seeds the backend, designs the presentation layer itself on the shipped hooks (product card/grid, PDP, home, theme), and releases to Wix hosting. Works on Wix-managed Astro (ambient auth, the default) and on any React-based project (Vite, non-Astro) over the public OAuth client id. Verticals: stores/storefront (products, categories, variants, cart, hosted checkout), bookings (services, appointment/class time slots, staff, booking form, checkout-or-place), blog (posts, categories/tags, rich content), cms (structured content collections), forms (schema-driven visitor forms: render, validate, submit), events (listing, RSVP, ticket sales), members (login, gated pages, account), portfolio (project collections, media galleries), pricing-plans (plan grid, hosted purchase), restaurants (menus, online ordering, table reservations). Triggers: build me a store/blog/booking/event/restaurant/portfolio site fast, take appointments fast, sell tickets or membership plans headless, wix headless fast, connect a Wix business app with ready-made SDK code."
+description: "Build a Wix Headless site fast by wiring SHIPPED, verified @wix/sdk code instead of authoring the integration from recipes. Each Wix business vertical ships a typed, framework-agnostic React core (data layer returning plain DTOs, hooks, headless components) plus an Astro overlay (SSR pages with owner-editable SEO pre-wired) and a build-time REST seed script — the agent scaffolds via the Wix CLI, deploys the shipped code, seeds the backend, designs the presentation layer itself on the shipped hooks (product card/grid, PDP, home, theme), and releases to Wix hosting. Works on Wix-managed Astro (ambient auth, the default) and on any React-based project (Vite, non-Astro) over the public OAuth client id. Verticals: stores/storefront (products, categories, variants, cart, hosted checkout), bookings (services, appointment/class time slots, staff, booking form, checkout-or-place), blog (posts, categories/tags, rich content), cms (structured content collections), forms (schema-driven visitor forms: render, validate, submit), events (listing, RSVP, ticket sales), members (login, gated pages, account), portfolio (project collections, media galleries), pricing-plans (plan grid, hosted purchase), restaurants (menus, online ordering, table reservations), faq (categorized questions and answers, search, a link per question), donations (campaign pages, goal progress, one-time and recurring donations via hosted checkout). Triggers: build me a store/blog/booking/event/restaurant/portfolio/FAQ/donation site fast, take appointments fast, sell tickets or membership plans headless, collect donations headless, wix headless fast, connect a Wix business app with ready-made SDK code."
 ---
 
 # Wix Headless Fast
@@ -74,7 +74,13 @@ doesn't express — or once the site exists and the work turns to managing or ex
   `capabilities.mediaUpload.policies` entry to the plan; Fast ships its client helper, Astro
   endpoint, dependencies, and generated policy module once. Read
   `templates/shared/CUSTOM_OPERATIONS.md` before choosing it. The agent wires the helper to
-  the product UI; it never authors or widens the endpoint.
+  the product UI; it never authors or widens the endpoint. For a site-wide search (a header box
+  with suggestions, a `/search?q=` page over the deployed verticals' products, services, posts
+  and events), add a `capabilities.siteSearch` entry; Fast ships its data layer, stores, hooks,
+  components and search page once. Enabling it means the Wix Site Search app is installed on the
+  site by the seed step (`install: true`; the capability's `seed/install.mjs`, run after the
+  content seed) — the index fills within about half a minute of the install. Playbook:
+  `templates/shared/capabilities/site-search/INSTRUCTIONS.md`.
 
 ## The run
 
@@ -83,9 +89,18 @@ Needed throughout: Node ≥ 20.11, git, a logged-in Wix CLI (`npx @wix/cli@lates
 read tokens into context), and the two companion skills beside this one, `wix-docs` and
 `wix-manage` (if `.agents/skills/` lacks them:
 `CI=1 npx skills@latest add wix/skills --skill wix-docs --skill wix-manage --yes`). The cold-start
-page, `cold-start/cold-start.md`, gets a machine with none of this to that point. Then fetch the shipped
+page, `cold-start/cold-start.md`, gets a machine with none of this to that point. In a folder that
+already holds a `wix.config.json`, `node <SKILL_ROOT>/install/context.mjs` first: it runs
+`wix env pull` when `.env.local` is missing and prints the two identities a project has — the
+deploy site (the config, where `wix release` goes) and the content site (the env, whose app the SDK
+client runs as and whose dashboard manages the business). They are one site, except on a
+**migration preview** (`guides/migration.md`), where the env names the site being migrated.
+Every script here reads that context; the site a call targets is never guessed from the config
+alone. Then fetch the shipped
 code once: `node <SKILL_ROOT>/install/templates.mjs`. It prints the folder;
 the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
+`node <SKILL_ROOT>/install/check.mjs` says whether the skill or its templates have a newer version
+and prints the update commands; it changes nothing.
 
 1. **Resolve the stack.** Default is **Wix-managed Astro** — take it unless the user names
    another framework or the directory already holds one. Then, by what the shipped code can run
@@ -157,13 +172,20 @@ the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
    - **`wix.config.json` and a project** → refuses: the folder is already a Wix project with a
      frontend, whether the CLI made it, a hand wrote it, or this skill built it. Three commands
      from the project root do everything setup would: `deploy.mjs <vertical…> --stack <stack>`
-     adds this skill's code or a solution (the client id is read from the config), then ONE
+     adds this skill's code or a solution (the client id comes from `.env.local`, the config as
+     the fallback), then ONE
      `npm install`, then the seed module if there is content to create. A project this skill
      built needs only the first, for a new solution; a change to what is built is file edits
      and a release.
-   - **`wix.config.json` and no project** (what `init` leaves in an empty folder) → the site
-     exists and has no frontend yet: `attach.mjs` (below), which takes the site from the config,
-     reuses its hosting, scaffolds and deploys. No seed: the site owns its content.
+   - **`wix.config.json` and no project, and `.env.local` declares a migration** (a project
+     downloaded from Wix for a site being moved to headless; the config names a site that only
+     hosts the deployment, the env the site being migrated) → **migrate**: setup copies the
+     vertical's composed template in around the config, deploys with the migrated site's app as
+     the client, starts the install, seeds nothing. `ready_for_brand_layer` says `mode: "migrate"`,
+     the parent as `siteId` and the child as `deploySiteId`. `guides/migration.md` has the rules.
+   - **`wix.config.json` and no project**, no migration (what `init` leaves in an empty folder) →
+     the site exists and has no frontend yet: `attach.mjs` (below), which takes the site from the
+     config, reuses its hosting, scaffolds and deploys. No seed: the site owns its content.
    - 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).
@@ -235,7 +257,10 @@ the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
    build+release mid-flow; backend content is fetched at
    runtime, so a re-release never "refreshes" seeded data. The run is complete only when the
    site is released — close with the live URL and the dashboard link
-   `https://manage.wix.com/dashboard/<siteId>`. **Copy the live URL verbatim from the
+   `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
    `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
    a 404).
 
@@ -264,6 +289,8 @@ close.
 | Portfolio/showcase: collections of projects, project pages with media galleries              | **portfolio**     | `templates/portfolio/INSTRUCTIONS.md`     |
 | Membership/subscription plans: pricing page, plan detail, hosted purchase                    | **pricing-plans** | `templates/pricing-plans/INSTRUCTIONS.md` |
 | Restaurant: menu with photos, online ordering, table reservations                            | **restaurants**   | `templates/restaurants/INSTRUCTIONS.md`   |
+| FAQ: questions grouped by category, search, expandable answers, a link per question         | **faq**           | `templates/faq/INSTRUCTIONS.md`           |
+| Donations: campaign pages, goal progress, one-time and recurring giving via hosted checkout   | **donations**     | `templates/donations/INSTRUCTIONS.md`     |
 
 Verticals compose: a brief that spans several (a restaurant with a blog, a store with member
 accounts) deploys them together — setup takes one vertical; deploy the rest with

package/skills/wix-headless-fast/cold-start/cold-start.md

@@ -1,6 +1,6 @@
 ---
 name: wix-headless-fast-cold-start
-description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants. Triggers: build me a store/blog/booking/events/portfolio/restaurant site fast, sell tickets or membership plans headless, wix headless fast entry."
+description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants, faq, donations. Triggers: build me a store/blog/booking/events/portfolio/restaurant/FAQ/donation site fast, sell tickets or membership plans headless, collect donations headless, wix headless fast entry."
 ---
 
 # Wix Headless Fast — cold start
@@ -45,7 +45,11 @@ existing session just reports `logged_in`).
 **Work from the folder that holds the project, or that will.** For a **new** build: an empty folder
 is the project; if the current folder holds unrelated things, make one named for the business and
 `cd` into it. For **connect**, **iterate** and **existing site**: you are already in it — the
-project's root, where its `package.json` or `index.html` is. Everything below — the
+project's root, where its `package.json` or `index.html` is. For a **project downloaded from Wix**
+(the brief gives a zip URL or path, typically a site being migrated to headless): download it and
+extract it into the working folder first, so that `wix.config.json` sits at the root, and work from
+there — the skill reads the folder and knows what it is; do not create a site, install apps or seed.
+Everything below — the
 bootstrap, the skills, the scaffold — lands in this folder, so a later session opened in the project
 finds all of it.
 

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

@@ -1,7 +1,9 @@
 # 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. `<SKILL_ROOT>` is the installed skill folder; the shipped code is
+and the frontend reads it live. (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").
 
 **Read the site, then run attach.** First, one call tells you what

package/skills/wix-headless-fast/guides/migration.md

@@ -0,0 +1,43 @@
+# A migration preview: a site being moved to headless
+
+Read when setup reports `mode: "migrate"`, or when a folder holds a `wix.config.json` and
+`node <SKILL_ROOT>/install/context.mjs` prints `migration.active: true`. The brief usually arrives
+as a project to download from Wix (a zip with the config), the names of the apps the site already
+has, and a request not to probe, install or seed anything.
+
+**Two sites, one project.** `wix.config.json` names a site created only to host the deployment:
+`wix release` goes there and nowhere else. `.env.local` (what `wix env pull` writes; setup and
+`context.mjs` pull it when it is missing) carries the credentials of the site being migrated, the
+**parent**, and says so. The parent owns everything the pages show and everything the business
+manages. So:
+
+- **The SDK client is the parent's.** The Astro integration reads `WIX_CLIENT_ID` from the env and
+  never the config; `deploy.mjs` copies the same value into `src/wix/config.ts` (react, lib) and
+  `js/wix/config.js` (static). Nothing in the data layer is told about the migration; it reads the
+  parent because its client is the parent's app.
+- **Admin, discovery and seed calls target the parent.** `read-site.mjs` and the seeds resolve the
+  site through `templates/shared/seed/site-context.mjs`; `wix-manage` recipes and any raw call take
+  `--site <parentSiteId>` (the `siteId` of the `ready_for_brand_layer` event). The dashboard link
+  is the parent's.
+- **Nothing is seeded, nothing installed.** The parent is a live site with its content; a seed
+  would write into the original. The seeds refuse on a preview unless run with `--allow-parent`,
+  which is the user's explicit decision, never a default. Apps are not installed: the brief names
+  what the site has, and the verticals follow from that list (Wix Stores → storefront, Wix
+  Bookings → bookings, Wix Forms → forms, and so on per the Verticals table; Wix Pro Gallery and
+  Wix Members Area map to portfolio and members). When the brief allows reading, the vertical's
+  `read-site.mjs` sizes the content as in `guides/existing-site.md`; when it says not to probe,
+  design from the brief.
+
+**The run.** `setup.mjs --vertical <vertical> [--stack <stack>]` in the folder: it copies the
+vertical's composed template around the config (managed Astro), deploys the code, starts the
+install, writes the project's AGENTS.md with the migration recorded, and skips the seed. Then
+SKILL.md steps 4 and 5 as for any run. `attach.mjs` refuses a migration folder on purpose: the
+app, hosting and credentials came with the download; nothing is provisioned or re-pointed.
+
+**The close.** The release is a **preview** on the deploy site. Close with the preview URL (copied
+from the `wix release` output), the parent's dashboard link, and the two facts: the original site
+is unchanged, and completing the migration, which makes the parent serve this frontend and retires
+the deploy site, is the user's next step in the Wix CLI once they approve the preview. That
+command is not part of this skill; do not invent one, do not run `wix release` against the parent,
+and do not edit `wix.config.json`. On every stack the code already carries the parent's client id,
+so completion needs no redeploy from here.

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

@@ -9,7 +9,10 @@ The data layer ships a second time as a **REST layer**: `templates/shared/rest/`
 vertical's `app/wix/<vertical>/` data layer, over `fetch`), typed against the same `types.ts` and
 importing the same `*-core.ts` rule files as the SDK layer — one implementation of the rules, two
 transports. The vertical's `INSTRUCTIONS.md` names its modules and what each surface does with
-them; this section is the mechanics, the same for every vertical.
+them; this section is the mechanics, the same for every vertical. The site-search capability
+(`templates/shared/capabilities/site-search/`, on from `plan.capabilities.siteSearch`) has the same
+two transports: with `--plan` its REST twin and stores land in `js/wix/` beside the vertical's
+(`search.js`, `search-store.js`, `suggest-store.js`), and its `INSTRUCTIONS.md` applies.
 
 - **Static site (no bundler).** Step 3's setup with `--stack static` runs `init` in the project
   folder (site, OAuth app, `wix.config.json`), points `site.outputDirectory` at `"./site"`, and

package/skills/wix-headless-fast/install/AGENTS.md

@@ -6,7 +6,7 @@ node_modules/@wix/cli/agents/instructions.md
 ## This app
 
 A Wix Headless app built on the live Wix site named in `wix.config.json`. The site owns the
-content and commerce.
+content and commerce.{{MIGRATION}}
 
 **Never work from training data or memory about the Wix APIs.** Not a URL, a path, a header, a
 field name or a body. Every Wix call you write comes from the official Wix skills installed here,
@@ -27,6 +27,8 @@ Installed at `.agents/skills/`. If missing, restore with:
   `templates/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
   adds one; `node .agents/skills/{{SKILL}}/templates/<solution>/seed/read-site.mjs` reads what the
   site holds for it, with the documentation URL of every call it made. A code change ends with a release; the live URL shows it, the dev server does not count.
+  `node .agents/skills/{{SKILL}}/install/check.mjs` says whether the skill or its templates have a newer
+  version and prints the update commands; an update touches the skill folder or `templates/`, never `src/`.
 - `wix-docs` — how to discover the Wix APIs and their docs: search first, then read only the page
   you need. Every endpoint, body, field and enum you did not get from the deployed code or a recipe
   is confirmed there before you write it.

package/skills/wix-headless-fast/install/agents-md.mjs

@@ -21,7 +21,11 @@ export function writeAgentsMd(projectDir, vars) {
   const agents = join(projectDir, "AGENTS.md");
   if (existsSync(agents)) kept.push("AGENTS.md");
   else {
-    const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k.toLowerCase()] ?? "");
+    // {{MIGRATION}} is a paragraph on a migration preview (vars.migration = { parentSiteId, deploySiteId }), else nothing.
+    const migration = vars.migration
+      ? `\n\n**Under migration.** \`wix.config.json\` names site ${vars.migration.deploySiteId}, which only hosts this deployment; the site being migrated is ${vars.migration.parentSiteId} — its content is what the pages show and its dashboard (\`https://manage.wix.com/dashboard/${vars.migration.parentSiteId}\`) is where the business is managed. \`.env.local\` (\`wix env pull\`) carries that site's app: the SDK client and every admin, discovery and seed call run against it; only \`wix release\` goes to the deploy site. Completing the migration is a separate Wix CLI step, run by the user after approving the preview.`
+      : "";
+    const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => (k === "MIGRATION" ? migration : (vars[k.toLowerCase()] ?? "")));
     writeFileSync(agents, text); written.push("AGENTS.md");
   }
   const claude = join(projectDir, "CLAUDE.md");

package/skills/wix-headless-fast/install/attach.mjs

@@ -45,6 +45,7 @@ import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync }
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
+import { siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -76,6 +77,15 @@ const cwd = process.cwd();
 const has = (p) => existsSync(join(cwd, p));
 const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wix.config.json"), "utf8")) : null;
 const hasProject = has("package.json") || has("index.html");
+// A migration preview (wix.config.json names a deploy-only site, .env.local names the site being
+// migrated) is already provisioned: its app, hosting and credentials came with the folder. Nothing
+// here applies — setup.mjs takes it (SKILL.md step 3).
+if (cwdConfig) {
+  const ctx = siteContext({ cwd });
+  if (ctx.migration.active) {
+    fail("place", `this folder deploys a migration preview of site ${ctx.migration.parentSiteId} (deploy site ${ctx.deploy.siteId}): the app and hosting are provisioned already — run setup.mjs --vertical <vertical> [--stack <stack>] here instead; nothing is attached or re-pointed`);
+  }
+}
 const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
 const stack = stackFlag ?? "astro";
 const knownVerticals = listVerticals(TEMPLATES);

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

@@ -0,0 +1,87 @@
+// Is there a newer version? Read-only: compares this installed skill and its templates with the
+// repository they came from and prints one JSON. It changes nothing and runs no update; the
+// commands that would are in the output.
+//
+//   node <SKILL_ROOT>/install/check.mjs
+//
+// Two layers, two answers:
+//   skill      the installed skill folder (SKILL.md, guides/, install/, cold-start/) 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.
+// Updating the skill changes how the agent works, not the project. Refreshing the templates changes
+// what future deploys copy and what the agent reads, not `src/`. Nothing here touches `src/`.
+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";
+
+const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 120_000, ...opts });
+const skillName = SKILL_ROOT.split("/").pop();
+const { repo } = installSource();
+
+const out = { skill: {}, templates: {}, update: {} };
+
+// ---- the repository: one clone of its history without file contents (small), read for both layers
+const tmp = mkdtempSync(join(tmpdir(), "wix-headless-fast-check-"));
+const clone = git(["clone", "--quiet", "--filter=blob:none", "--no-checkout", "--single-branch", repo, tmp]);
+if (clone.status !== 0) {
+  rmSync(tmp, { recursive: true, force: true });
+  console.log(JSON.stringify({ error: `could not reach ${repo}: ${(clone.stderr || "").trim().slice(-200)}` }));
+  process.exit(1);
+}
+const head = git(["-C", tmp, "rev-parse", "HEAD"]).stdout.trim();
+
+// ---- skill folder: every installed file's blob hash against the head's tree -------------------
+{
+  const tree = git(["-C", tmp, "ls-tree", "-r", head, "--", `skills/${skillName}`]).stdout;
+  const remote = new Map(tree.split("\n").filter(Boolean).map((l) => { const [meta, path] = l.split("\t"); return [path.slice(`skills/${skillName}/`.length), meta.split(" ")[2]]; }));
+  const local = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.name === "templates" && dir === SKILL_ROOT) continue; // the templates are the other layer
+      if (e.isDirectory()) walk(p); else local.push(relative(SKILL_ROOT, p));
+    }
+  };
+  walk(SKILL_ROOT);
+  const differs = [], missingHere = [];
+  for (const f of local) if (remote.get(f) !== git(["hash-object", join(SKILL_ROOT, f)]).stdout.trim()) differs.push(f);
+  for (const f of remote.keys()) if (!local.includes(f)) missingHere.push(f);
+  out.skill = differs.length || missingHere.length
+    ? { status: "behind", differs, ...(missingHere.length ? { missingHere } : {}), note: "a file that differs may also be one edited here; the update reinstalls the skill folder" }
+    : { status: "current" };
+}
+
+// ---- templates: the recorded commit against the head ------------------------------------------
+let dir = null;
+try { dir = templatesDir(); } catch (e) { out.templates = { status: "unknown", detail: e.message }; }
+if (dir) {
+  const src = templatesSource(dir);
+  if (src.checkout) out.templates = { status: "checkout", dir };
+  else if (!src.commit) out.templates = { status: "unknown", detail: "no commit recorded in templates/.source" };
+  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);
+    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.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?)";
+    }
+  }
+}
+rmSync(tmp, { recursive: true, force: true });
+
+// ---- what would act on each ------------------------------------------------------------------
+const rel = relative(process.cwd(), SKILL_ROOT) || ".";
+out.update = {
+  skill: `CI=1 npx skills@latest update ${skillName} --yes   (or: gh skill update ${skillName})`,
+  templates: `node ${rel}/install/templates.mjs --refresh   (then commit the changed files under ${rel}/templates)`,
+  note: "neither touches src/; a shipped fix reaches the project by comparing its copy with the template",
+};
+console.log(JSON.stringify(out, null, 2));

package/skills/wix-headless-fast/install/context.mjs

@@ -0,0 +1,126 @@
+// The site context of a project folder — the one place that says which site a call targets.
+//
+//   node <SKILL_ROOT>/install/context.mjs [--refresh] [--no-pull]     (prints one JSON object)
+//
+// Two identities live in a Wix project and are the same site almost always:
+//   deploy  — `wix.config.json` (`siteId`, `appId`): where `wix release` uploads. The CLI's business.
+//   content — `.env.local` (`WIX_CLIENT_ID`, what `wix env pull` writes): the app the SDK client
+//             runs as, on every stack (the Astro integration reads WIX_CLIENT_ID from the env and
+//             never the config; the other stacks get it copied into src/wix/config.ts by deploy.mjs).
+// They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
+// host the deployment, while `.env.local` carries the credentials of the site being migrated (the
+// parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
+// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
+// that does not exist yet; this module only reads the state.
+//
+// `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
+// identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
+// reported in `pullError` and the config's ids stand in, so a caller can still work offline.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// The variables `wix env pull` writes for a migration preview. The names are the platform's and are
+// spelled once, here.
+export const ENV = {
+  clientId: "WIX_CLIENT_ID",
+  parentSiteId: "WIX_MIGRATION_PARENT_SITE_ID",
+  migration: "WIX_MIGRATION",
+};
+
+/** KEY=value lines of a dotenv file, quotes stripped; null when the file is absent. */
+export function readEnvFile(file) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function readWixConfig(cwd) {
+  const file = join(cwd, "wix.config.json");
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+const truthy = (v) => typeof v === "string" && /^(1|true|yes|on)$/i.test(v.trim());
+
+const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
+
+/**
+ * `wix env pull` into `cwd/.env.local`. The CLI mounts `env` only once the folder reads as an Astro
+ * project (an astro.config.* file, or `site.outputDirectory` in the config); a folder that holds just
+ * the downloaded `wix.config.json` gets "unknown command 'env'". Then the pull runs in a temp folder
+ * holding a copy of the config and an empty astro.config.mjs, and the `.env.local` comes back here.
+ */
+export function pullEnv(cwd) {
+  const envFile = join(cwd, ".env.local");
+  let r = runPull(cwd);
+  if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
+  const notAProjectYet = /unknown command 'env'/.test(`${r.stderr}${r.stdout}`);
+  if (notAProjectYet) {
+    const tmp = mkdtempSync(join(tmpdir(), "wix-env-pull-"));
+    try {
+      copyFileSync(join(cwd, "wix.config.json"), join(tmp, "wix.config.json"));
+      writeFileSync(join(tmp, "astro.config.mjs"), "");
+      r = runPull(tmp);
+      if (r.status === 0 && existsSync(join(tmp, ".env.local"))) {
+        copyFileSync(join(tmp, ".env.local"), envFile);
+        return { ok: true, via: "stub project" };
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
+}
+
+/**
+ * `{ deploy: { siteId, appId }, content: { siteId, clientId }, migration: { active, parentSiteId },
+ *    env: { file, present, pulled }, pullError?, warnings: [] }`.
+ * `pull`: "auto" (default) pulls when `.env.local` is missing; true always; false never.
+ */
+export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
+  const config = readWixConfig(cwd) ?? {};
+  const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
+  const envFile = join(cwd, ".env.local");
+  let pulled = false, pullError;
+  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
+    const r = pullEnv(cwd);
+    if (r.ok) pulled = r.via;
+    else pullError = r.error;
+  }
+  const env = readEnvFile(envFile) ?? {};
+  const parentSiteId = env[ENV.parentSiteId] || null;
+  const active = !!parentSiteId && (truthy(env[ENV.migration]) || env[ENV.migration] === undefined);
+  const migration = { active, parentSiteId: active ? parentSiteId : null };
+  const clientId = env[ENV.clientId] || deploy.appId;
+  const content = { siteId: active ? parentSiteId : deploy.siteId, clientId };
+  const warnings = [];
+  if (env[ENV.clientId] && deploy.appId && env[ENV.clientId] !== deploy.appId && !active) {
+    warnings.push(`.env.local ${ENV.clientId} differs from wix.config.json appId and no migration is declared — the SDK client runs as the env's app, the release goes to the config's site`);
+  }
+  if (active && migration.parentSiteId === deploy.siteId) {
+    warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
+  }
+  return { deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
+}
+
+// ---- CLI ----------------------------------------------------------------------------------------
+if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
+  const argv = process.argv.slice(2);
+  const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
+  console.log(JSON.stringify(siteContext({ pull }), null, 2));
+}