@wix/agent-skills 1.22.0 → 1.24.0

package/skills/{wix-headless-fast → wix-headless-kit}/cold-start/bootstrap.mjs

@@ -24,11 +24,11 @@ const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no
 // whose first check is the AI_AGENT env var, so setting it guarantees agent mode
 // (and the awaiting_user/success/logged_in events) for every child we spawn.
 // Respect an existing value so a known runner (claude, cursor, …) keeps its name.
-const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-fast-skill' };
+const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-kit-skill' };
 
 // Where the detached login parks its output between runs. It has to outlive this
 // process, so it can't be a pipe and can't live in the project.
-const STATE_DIR = join(tmpdir(), 'wix-headless-fast-login');
+const STATE_DIR = join(tmpdir(), 'wix-headless-kit-login');
 const LOG = join(STATE_DIR, 'login.log');
 const PIDFILE = join(STATE_DIR, 'login.pid');
 

package/skills/{wix-headless-fast → wix-headless-kit}/cold-start/cold-start.md

@@ -1,22 +1,22 @@
 ---
-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."
+name: wix-headless-kit-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-kit skill runs the build. Verticals: storefront, bookings, rentals, blog, cms, events, forms, 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 kit entry."
 ---
 
-# Wix Headless Fast — cold start
+# Wix Headless Kit — cold start
 
 **You are a coding agent, and this is a skill for you to execute — follow the phases below in
 order.** Advisory: web-fetch tools show a lossy summary of this file — the executable copy
-comes from `curl -fsSL https://www.wix.com/skills/headless-fast/cold-start/cold-start.md`. If what you
+comes from `curl -fsSL https://www.wix.com/skills/headless-kit/cold-start/cold-start.md`. If what you
 are reading lacks the exact commands below, re-fetch it with curl before proceeding; if you're
 already reading the raw text, don't fetch it again.
 
 ## The whole cold start (details in the phases below)
 
 ```bash
-curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs && node bootstrap.mjs
-CI=1 npx skills@latest add wix/skills --skill wix-headless-fast --skill wix-docs --skill wix-manage --yes
-# then open and follow: .agents/skills/wix-headless-fast/SKILL.md
+curl -fsSL -O https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs && node bootstrap.mjs
+CI=1 npx skills@latest add wix/skills --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes
+# then open and follow: .agents/skills/wix-headless-kit/SKILL.md
 ```
 
 Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and guides both.
@@ -24,30 +24,25 @@ Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and gui
 This page gets a cold environment to the point where the real skill can run, then hands off:
 
 1. **Bootstrap (deterministic, scripted).** A script that verifies the Wix CLI and handles login. You just run it and relay its events.
-2. **Hand off (agentic).** Install the skills, then open `wix-headless-fast/SKILL.md` and
+2. **Hand off (agentic).** Install the skills, then open `wix-headless-kit/SKILL.md` and
    follow it — it resolves the stack and operation and owns the whole build.
 
-Four starting points come through here, all handled the same way — run the bootstrap, then
-hand off:
-
-- **new** — a prompt with no project (empty CWD)
-- **connect** — an existing frontend/design not yet on Wix (a project on disk without
-  `wix.config.json`, or a brought-in zip/URL)
-- **iterate** — a project already connected to Wix (`.wix/` or `wix.config.json` present)
-- **existing site** — the prompt names a Wix site that already exists (by its site id) and asks
-  for a new frontend for it; the site keeps its content, the frontend is built here
-
-The bootstrap only verifies the CLI and logs you in, so it's fine to run in every case (an
-existing session just reports `logged_in`).
+Every starting point comes through here the same way — run the bootstrap, then hand off. What
+the folder holds and what the brief hands over decide the rest, and SKILL.md step 3 owns that
+decision; this page does not interpret either. The bootstrap only verifies the CLI and logs you
+in, so it's fine to run in every case (an existing session just reports `logged_in`).
 
 ## Phase 0 — The project's folder, and Node
 
-**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
-bootstrap, the skills, the scaffold — lands in this folder, so a later session opened in the project
-finds all of it.
+**Work from the folder that holds the project, or that will.** An empty folder is the project for
+a new build; if the current folder holds unrelated things, make one named for the business and `cd`
+into it. A project already on disk is its own folder — its root, where the `package.json`,
+`index.html` or `wix.config.json` is. **Whatever the brief hands over as files goes into that folder
+first**, before Phase 1: a zip is extracted there, a URL is downloaded and extracted there, so that
+anything it carries — a `wix.config.json` included — sits at the root. Do not interpret what is
+there: the skill reads the folder and knows what it is. Everything below — the bootstrap, the
+skills, the scaffold — lands in this folder too, so a later session opened in the project finds all
+of it.
 
 The Wix CLI requires **Node ≥ 20.11**. Check `node -v`; if it errors or prints a lower
 version, install or upgrade Node first — do **not** work around it:
@@ -69,9 +64,9 @@ externally-downloaded code.
 
 ```bash
 # macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs
+curl -fsSL -O https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs
 # Windows PowerShell:
-iwr https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs -OutFile bootstrap.mjs
+iwr https://www.wix.com/skills/headless-kit/cold-start/bootstrap.mjs -OutFile bootstrap.mjs
 
 node bootstrap.mjs
 ```
@@ -97,15 +92,15 @@ parsed:
 
 ```bash
 CI=1 npx skills@latest add wix/skills \
-  --skill wix-headless-fast --skill wix-docs --skill wix-manage --yes
+  --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes
 ```
 
-- **`wix-headless-fast`** — the build itself.
+- **`wix-headless-kit`** — the build itself.
 - **`wix-docs`** — the API reference the playbooks defer to for any contract they don't cover.
 - **`wix-manage`** — management recipes, for admin work on the site after it exists.
 
 They land under `.agents/skills/`. Then **open
-`.agents/skills/wix-headless-fast/SKILL.md` and follow it** — it owns the rest of the run:
+`.agents/skills/wix-headless-kit/SKILL.md` and follow it** — it owns the rest of the run:
 resolve the stack, scaffold, deploy the shipped code, seed, build the brand layer, release.
 (A request outside the shipped verticals — see its SKILL.md § Verticals — is built from the Wix
 API reference through `wix-docs`, on the same project; SKILL.md says how.)

package/skills/wix-headless-kit/guides/capabilities.md

@@ -0,0 +1,76 @@
+# Capability map: which Wix product owns what, and what this skill ships for it
+
+Read this when the Verticals table in SKILL.md does not settle the match: the brief names a Wix
+product or a feature the table does not mention, two rows could fit, or the request sounds like a
+vertical this skill does not ship. Every Wix product, its docs path (relative to
+`https://dev.wix.com/docs/api-reference/`), the features its introduction page lists, and the
+column that matters here: what this skill ships for it. Features come from the introduction pages;
+when a product looks wrong or missing, re-derive from `<path>/introduction.md` through `wix-docs`.
+
+"Shipped" means the vertical's data layer, stores, hooks, components and seed cover it; "read only"
+means the DTO carries it but nothing acts on it; "not shipped" means the feature is built from the
+API reference through `wix-docs` on the same project, with the same rules as every other call.
+
+## Business solutions
+
+| Product | Path | Features (from the introduction page) | This skill |
+|---|---|---|---|
+| Stores | `business-solutions/stores` | Products, categories, options and variants, inventory, brands, ribbons, info sections, customizations (modifiers), promotions, store locations, site currency, currency conversion | **storefront**: products, categories, options and variants, inventory and low stock, pre-order, ribbons, info sections, modifiers, discount names, subscriptions, back in stock, site currency (set by the seed). Not shipped: brands, store locations, currency conversion |
+| eCommerce | `business-solutions/e-commerce` | Cart, checkout, abandoned checkout, orders, transactions, fulfillment, discount rules, recommendations, shipping rates, additional fees, payments, catalog | **storefront**, **restaurants**, **bookings**, **events**, **donations** use it for the cart line, totals (discounts, fees, taxes), coupon code, buyer note and the checkout redirect session; order read on the events and donations thank-you pages. Not shipped: abandoned checkout, fulfillment, shipping rates, recommendations |
+| Coupons | `business-solutions/coupons` | Coupons, percentage and fixed discounts, free shipping, buy X get Y, scopes, usage limits, expiry | Applied at the cart by **storefront**; created through a `wix-manage` recipe when the brief asks (no coupon seed) |
+| Bookings | `business-solutions/bookings` | Services, appointments, classes, courses, staff, resources, pricing, policies, time slots, bookings, waitlists, external calendar, checkout and orders | **bookings**: appointments, classes and courses, staff, time slots and sessions, rate types, deposits, policies as the call to action, locations, categories, booking to checkout or direct placement. Read only: waitlist flag on a slot, add-ons. Not shipped: non-staff resources, external calendar |
+| Rentals | `business-solutions/rentals` | Rental services, hourly and daily durations, customer-selected length, bookable resources, resource attributes, per-hour and per-day pricing, availability, consecutive multi-day bookings | **rentals**: the catalog (Bookings services carrying the Rentals app id), hourly starts then end options, daily starts then the consecutive-day walk, the server-priced quote, the Rentals booking form, booking with the start's resource and the customer's end, checkout-or-place; the seed creates resource types, resources (bookable around the clock) and rental services one at a time. Not shipped: resource attributes and attribute filters, per-resource working hours (which split a multi-day rental into one booking per day), multi-service bookings |
+| Meetings | `business-solutions/meetings` | Scheduling links, shareable booking page, duration and location, video or phone or in person, hosts, calendar sync, intake forms, paid meetings, rescheduling | **Not shipped.** Also Bookings underneath; a scheduling-link brief is built through `wix-docs` |
+| Restaurants | `business-solutions/restaurants` | Menus, sections, items, variants, modifiers, labels, online orders, operations, fulfillment methods, availability exceptions, service fees, reservations, time slots, experiences | **restaurants**: menus, sections, items, variants, modifier rules, labels, ordering (operations, fulfillment methods, windows), reservations with the location's form and time slots, money from the eCommerce settings. Not shipped: service fees in the menu totals, experiences |
+| Events | `business-solutions/events` | Events, ticket definitions, tickets, RSVP, orders and checkout, check-in, guests, guest list, schedule, policies | **events**: listing and event pages, occurrences, RSVP with the organizer's form and guest control, ticket tiers to checkout, order read on the confirmation page, categories. Not shipped: check-in, guest list, schedule |
+| Blog | `business-solutions/blog` | Posts, draft posts, categories, tags, post stats, blog roles, paid post subscriptions | **blog**: feed, post pages, categories and tags, authors, metrics, likes, related posts, comments through Community. Seed writes draft posts and publishes them. Not shipped: paid post subscriptions, roles |
+| CMS | `business-solutions/cms` | Data items, collections, collection permissions, aggregations, indexes, external databases, backups, background tasks | **cms**: collections and items with filters, sort, distinct values, paging, references, permissions set by the seed. Not shipped: indexes, external databases, backups |
+| Pricing Plans | `business-solutions/pricing-plans` | Plans, orders, recurring, single payment, free plans, free trials, cancellation, credits | **pricing-plans**: plans with trials and fees, the plan gate on the member's orders, purchase through the native checkout redirect. Not shipped: cancellation, credits |
+| Portfolio | `business-solutions/portfolio` | Projects, project items, collections, settings, gallery layouts, cover media | **portfolio**: collections, projects, galleries with images and video. Not shipped: settings |
+| Donations | `business-solutions/donations` | Campaigns, goals, one-time and recurring, predefined and custom amounts, cover fees, progress | **donations**: all of it, through the eCommerce checkout |
+| Gift Cards | `business-solutions/gift-cards` | Gift cards, gift card products, redemption codes, balances, denominations, expiry, transactions | Not shipped |
+| Benefit Programs | `business-solutions/benefit-programs` | Programs, templates, tiers, credits, redemption, enrollment, balances, eligibility | Not shipped; program activation is dashboard-only |
+| Suppliers Hub | `business-solutions/suppliers-hub` | Marketplace products, suppliers, dropshipping, wholesale tiers | Not shipped; partner-only |
+| Forum | `business-solutions/forum` | Deprecated (discontinued March 2026) | Not shipped; do not build on it. Discussion is blog comments or Community groups |
+
+## Site-wide products
+
+| Product | Path | Features | This skill |
+|---|---|---|---|
+| Members & Contacts | `crm/members-contacts` | Contacts, labels, extended fields, notes, members, profiles, authentication, privacy, badges, followers | **members**: sign-up, login, verification, logout, the current member's profile, gated pages. Not shipped: contacts, labels, badges, followers, profile editing |
+| Forms | `crm/forms` | Form schemas, submissions, templates, intake forms, interactive sessions, chat settings | **forms**: the schema rendered live, every field kind, rules, steps, submissions with files (paid plans) or through the media-upload capability. Not shipped: templates, interactive sessions, chat |
+| FAQ | `business-management/faq-app` | Categories, question entries | **faq**: all of it |
+| Site Search | `business-management/site-search` | Search, search schemas | the **site-search** capability: federated search and suggestions over the deployed verticals |
+| Media Manager | `assets/media` | Files, folders, upload URLs | the **media-upload** capability (a validated Astro endpoint and a client helper); images in every seed |
+| SEO | `business-management/seo` | Site tags, patterns, item tags, resolved tags, redirects | owner-editable item SEO on every Astro item page that has a Wix SEO item type (products, posts, services, events, categories) |
+| Community | `crm/community` | Groups, membership, comments, reviews, moderation | Comments only, inside **blog**. Not shipped: groups, reviews |
+| Loyalty Program | `crm/loyalty-program` | Points, earning rules, tiers, accounts, rewards, loyalty coupons | Not shipped |
+| Online Programs | `business-management/online-programs` | Programs, sections, steps, enrollment, payment | Not shipped (a paid course a member enrolls in is pricing-plans plus gated pages, or this) |
+| Locations | `business-management/locations` | Locations, default location, business schedule, special hours | Read by **bookings** and **restaurants** for their locations; not managed |
+| Communication, CRM, Automations, Marketing, Payments, Get Paid, Multilingual, Notifications, Branches, Analytics, Calendar | `crm/…`, `business-management/…` | see each introduction page | Not shipped; back-office or infrastructure, driven from `wix-manage` recipes or `wix-docs` when a brief needs one |
+
+## Where things actually live
+
+- Meetings and Rentals ship no APIs of their own: both are Bookings with restricted field values,
+  so their contracts are the Bookings ones. A rentals site also needs the Wix Bookings app installed
+  (the rentals seed does it): with Rentals alone, availability for an hourly rental with several
+  units answers 401 "Booking app not installed".
+- Loyalty coupons (`crm/loyalty-program/rewards/coupons`) are a different resource from eCommerce
+  Coupons (`business-solutions/coupons`).
+- Stores categories are called Collections in Catalog V1 and Categories in Catalog V3; the shipped
+  code is V3.
+- SEO spans two products: the tag model is `business-management/seo`; Ads.txt and keyword
+  suggestions are under `business-management/marketing/seo`.
+- Badges and Followers live under `crm/members-contacts/members/activity/`, profiles under
+  `members/member-management/members-about-v2`, privacy under `member-management/privacy`.
+- There is no roles API and no segments API; contact labels serve segmentation.
+- Stores, Coupons and Suppliers Hub have no usable introduction page; start from the menu page and
+  the sub-section introductions.
+
+## When the brief lands on "not shipped"
+
+Say so plainly in one line, then build it on the same project and stack from the API reference
+through `wix-docs` (search, then the method page), with every other rule unchanged: nothing from
+memory, live data or an honest empty state, purchases through Wix. Choose the closest shipped
+vertical as the base when one exists (a meetings brief starts from bookings, a loyalty brief from
+members), and name the gap in the closing message.

package/skills/{wix-headless-fast → wix-headless-kit}/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-kit/guides/feedback.md

@@ -0,0 +1,98 @@
+# Feedback: relay the user's building-with-Wix experience to Wix
+
+A small, optional step: send the user's feedback about the experience of building with Wix to Wix,
+attributed to the authenticated user. It closes the loop when this skill, the shipped code, the
+APIs, the docs or the tooling got in the way. It is not support and not about the user's site
+content; it is feedback about building with Wix.
+
+## When to offer it
+
+Sending is always the user's call. Offering is not: default to offering, in plain prose, once per
+issue, in any of these cases, and send only after an explicit yes.
+
+- The user asks to send feedback or report something to Wix. Confirm the wording and send.
+- The user complains, is frustrated, or reports a Wix bug while you work. Acknowledge, then offer.
+- The run hit friction, even once. Friction is anything that cost more turns than it should have,
+  whether or not it ended in an error: a confusing error, a doc that was wrong or missing, a seed
+  step that failed and had to be re-run, a shipped file that did not cover what the brief needed, a
+  playbook line you had to read the source to understand, a contract you had to discover by trial,
+  a slow install or a flaky call you retried, a workaround you had to invent, a platform gate the
+  brief did not anticipate (a plan restriction, a missing payment method), a step where you were
+  unsure what the skill wanted. Offer in the moment: "That tripped us up; want me to send it to Wix
+  as feedback?"
+- At the close of every run, before the live URL and the dashboard link, run a self-check over the
+  whole session. Friction you shrugged off or silently retried past is still signal. If anything
+  qualifies, offer before you sign off. Skip the offer only when the run was clean end to end.
+
+When you offer, invite the user to add anything in their own words; it goes into the message
+verbatim under "In the user's words". Never send on a single transient error, never without a yes,
+never twice for the same issue. When unsure, ask.
+
+## Compose the message
+
+Wix receives free text, so a bare sentence is low signal. Send a summary of the whole run in three
+layers, so Wix can triage without chasing you.
+
+**Provenance**, as labelled lines; drop what does not apply, add what helps:
+
+```
+Agent / model: <Claude Code / Opus, Cursor, Codex, ...>
+Skill: wix-headless-kit <version from .agents/skills/wix-headless-kit/SKILL.md or skills-lock.json> · run kind: <create | connect | attach | iterate | reference mode | migration preview>
+Stack: <astro | react | lib | static | port> · verticals: <storefront, blog, ...> · capabilities: <media-upload, site-search, none>
+Wix tooling used: <Wix CLI, wix-manage recipes, wix-docs, REST via curl>
+Wix products: <Stores, Bookings, Events, Blog, Forms, ...>
+Site: <siteId> · public clientId: <appId> · dashboard: <url> · live: <url>
+Skill files involved: <templates/<vertical>/seed/seed-<v>.mjs, templates/<vertical>/INSTRUCTIONS.md, install/setup.mjs, ...>
+Other ids: <product / service / form / event ids created this run, as relevant>
+```
+
+**Narrative:**
+
+- In the user's words: what they added when you offered, verbatim, secrets redacted. Skip when empty.
+- User intent and run summary: what they set out to build and the arc of the session in a few
+  sentences, what worked and what fought back.
+- Conversation and agent flow: a condensed play-by-play, the key exchanges, the scripts and calls
+  you ran, what came back, the decisions and course corrections. Distilled, not a transcript.
+- Friction points: the heart of it. Every place something got in the way, each with the step or
+  endpoint, the status and message, the gap, the workaround and what you expected instead, with a
+  minimal repro where there is one. Include the ones you recovered from.
+
+**Attribution**, per significant friction point, your best diagnosis tagged with one of: API
+behavior, API schema, API reference docs, docs articles or examples, Wix harness (CLI, auth, hosting),
+this skill's shipped code, this skill's playbook, other or unsure; and whether you confirmed it or
+are assuming. A wrong route is worse than "unsure".
+
+**Bottom line**: one or two sentences naming the single most important problem and its impact,
+worst first, plainly, in a professional register.
+
+Confirm the final wording with the user before sending. Never include secrets (no bearer tokens,
+refresh tokens, API keys, credentials) and no personal data beyond what the feedback needs.
+
+## Send it
+
+The call identifies the human account, so it needs a user-scoped bearer from the bare token
+command, not the site-scoped one the seeds use (`token --site` carries a metaSiteId and the service
+rejects it as anonymous).
+
+```bash
+TOKEN=$(npx @wix/cli@latest token)
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/mcp-serverless/v1/headless-feedback" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"<composed feedback>"}'
+```
+
+- `HTTP_STATUS:200` with `{}`: sent. Tell the user.
+- `500` "Unable to determine target user id, anonymous messages are not allowed": the token was
+  site-scoped. Re-mint with the bare command and retry once.
+- `401` or `403`: the CLI session expired. `npx @wix/cli@latest login` (surface the URL and code to
+  the user), re-mint, retry once. If it still fails, show the response and stop.
+
+## Rules
+
+- Offer whenever the run warrants it; send only after an explicit yes.
+- One submission per issue; no retries beyond the one named above, no duplicates.
+- Specific and factual; wording confirmed first.
+- No tokens, secrets, credentials or unnecessary personal data in the message.
+- Not for the user's site content and not a support channel.

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

@@ -0,0 +1,54 @@
+# 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 is the prompt
+the Wix dashboard's Headless settings hand the owner after "Go Headless": download the project from
+`https://manage.wix.com/download-headless-business/<siteId>/download.zip`, the names of the apps
+the site already has, and the instruction not to probe, install or seed anything. The zip holds
+`wix.config.json` (the deploy site and its app) beside the CLI's blank Astro starter.
+
+**What `.env.local` says.** `wix env pull` copies the project's `prod` environment: the parent's
+`WIX_CLIENT_ID`, and the migration's own variables, `EDITOR_MIGRATION_STATUS` (`ACTIVE` while the
+migration is under way, `COMPLETED` once the parent serves this frontend), `EDITOR_MIGRATION_PARENT_SITE_ID`,
+`EDITOR_MIGRATION_CHILD_SITE_ID` and `EDITOR_MIGRATION_CHILD_APP_ID`. `context.mjs` reads the first
+two; the shape is `migration` whenever the status is active, whatever else the folder holds.
+
+**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>[,<vertical>…] [--stack <stack>]` in the folder (every vertical the brief needs, in one call): it keeps the
+starter the download carries and deploys the vertical's code and dependencies into it (a bare config
+gets the composed template copied in around it), 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 once they approve the preview: the dashboard hands them
+a second prompt for it (`wix env pull`, `wix finalize-migration`, `wix build`, `wix release`, in
+that order). That step is not part of this skill and the command may not be in the installed CLI
+yet; 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 → wix-headless-kit}/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 → wix-headless-kit}/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,11 @@ 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/`.
+  When Wix gets in the way of a change here (a confusing error, a doc gap, a workaround you had to
+  invent), offer to relay it to Wix per `.agents/skills/{{SKILL}}/guides/feedback.md`; send only after
+  an explicit yes.
 - `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 → wix-headless-kit}/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 → wix-headless-kit}/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 { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -75,7 +76,19 @@ const subfolder = argv.includes("--subfolder");
 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 frontend here: a package.json, an index.html at the root, or an index.html in the folder the
+// config's site.outputDirectory names (a static site laid out for release) — install/context.mjs.
+const fp = frontendPresent(cwd);
+const hasProject = fp.packageJson || fp.rootIndex || fp.outputIndex;
+// 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-kit/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-kit-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));