@wix/agent-skills 1.23.0 → 1.25.0

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

@@ -1,9 +1,9 @@
 ---
-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), 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."
+name: wix-headless-kit
+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), rentals (rooms, vehicles, gear by the hour or the day: resources, customer-picked length, priced quote, checkout), 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/rental/event/restaurant/portfolio/FAQ/donation site fast, take appointments fast, rent out rooms/cars/equipment headless, sell tickets or membership plans headless, collect donations headless, wix headless kit, connect a Wix business app with ready-made SDK code."
 ---
 
-# Wix Headless Fast
+# Wix Headless Kit
 
 Build a Wix Headless site on **shipped, verified code instead of authoring the integration**.
 Each vertical ships the integration itself — a typed data layer, hooks, components, pages, and a
@@ -86,22 +86,30 @@ doesn't express — or once the site exists and the work turns to managing or ex
 
 Needed throughout: Node ≥ 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 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. In a folder that
+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
+when there is none; the cold-start page, `https://www.wix.com/skills/headless-cold-start/headless-kit.md`,
+gets a machine with none of this, the skills included, 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
+`wix env pull` when `.env.local` is missing and prints the folder's **shape** (`folder.shape`, the
+cases of step 3, with the `next` for each) and 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.
 
+Throughout any run: if the user asks to send feedback to Wix, complains or gets frustrated, or the
+run hits friction of any kind: anything that cost more turns than it should have, whether or not
+it ended in an error (a confusing error, a doc gap, a seed that had to be re-run, a shipped file
+that did not cover the brief, a playbook line you had to read the source to understand, a call you
+had to work out by trial, a workaround you had to invent, a slow or flaky step, a platform gate),
+offer to relay it to Wix per `<SKILL_ROOT>/guides/feedback.md`. Default to offering rather than waiting to be asked; send
+only after an explicit yes, never automatically. Step 5 ends with the same self-check.
+
 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
    there:
@@ -143,59 +151,58 @@ and prints the update commands; it changes nothing.
      the OAuth app's allowed domains before checkout can return to it.
    - **Static** (no build): `outputDirectory` points at the folder the pages live in; a route is a
      page plus a query-string slug (reference mode).
-2. **The seed plan.** When the brief 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 else 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.
-   Draft a plan from the brief only when nothing was supplied (read only the vertical's
-   `SEED.md` for this — it depends only on the brief; save the vertical's `INSTRUCTIONS.md` for
-   step 4, where it's needed). **An existing site has no plan**: when the brief names a site by
-   its id, the site holds the content already — nothing is seeded, and the frontend reads what
-   is there (step 3's attach path).
+2. **The seed plan.** The brief decides what is seeded; a site this run makes always opens with content:
+
+   | the brief | the plan |
+   |---|---|
+   | 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 |
+
+   **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
+   (step 3's attach path), and only content the brief supplies or describes is added to it.
 3. **Set up the project, in its folder** — one deterministic call, the same for an empty folder
-   and for a project already on disk; **the folder decides** what it does:
+   and for a project already on disk; **the folder decides** what it does, from five file facts:
+   `wix.config.json`, its `site.outputDirectory`, the migration variables in `.env.local`,
+   `package.json`, `index.html`. `node <SKILL_ROOT>/install/context.mjs` prints the shape it reads
+   and the `next` for it. **The brief is the instruction**: what it asks to switch on is installed
+   on the site the folder names, without asking again. Ask only when acting would create a second
+   site for a folder that already has one, or when a cleanup seems needed.
 
    ```bash
-   node <SKILL_ROOT>/install/setup.mjs --vertical <vertical> [--plan plan.json] [--business-name "<Brand>"]
+   node <SKILL_ROOT>/install/setup.mjs --vertical <vertical>[,<vertical>…] [--plan plan.json] [--business-name "<Brand>"] [--stack <stack>]
    ```
 
-   - **Empty** (or only loose files: a CSV, a brief) → **create**: `wix create` with the
-     vertical's composed template, here; `--business-name` names the site.
-   - **A project without `wix.config.json`** (a `package.json`, or an `index.html` at the root:
-     someone's Astro, Vite, Next, plain HTML) → **connect**: `init` in place links the folder
-     to a new site (the site is named after the folder), then the shipped code deploys into
-     the project as it is. Pass `--stack` for the stack you resolved in step 1, and make the
-     project what that stack needs on Wix hosting (step 1) before or right after the call.
-     With `--stack static` setup also makes `site/` the folder `wix release` uploads and deploys
-     the REST layer into `site/js/wix/`; you move the pages, styles and assets in (`guides/reference-mode.md`).
-   - **`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 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, 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.
+   Name every vertical the brief needs in this one call (a store with member accounts is
+   `storefront,members`): the first one's template scaffolds the project; the others deploy in the
+   same call, so the one install covers them all. A vertical added after the install has started
+   costs a second install.
+
+   | the folder holds | shape | what setup does | seeded by setup |
+   |---|---|---|---|
+   | 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 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.
+
    - 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).
 
-   `--vertical` is required and picks which shipped code deploys AND which seed runs — use
-   the vertical you resolved from the Verticals table. **`--plan` decides whether anything is
-   seeded**: pass the plan from step 2 when there is one; a site that already holds its content
-   gets none. Seeding is **additive**: it never deletes or overwrites what the site holds; if a
-   cleanup seems needed, ask. The `ready_for_brand_layer` event says `mode` (create or
-   connect), the stack, and the `next` for that stack, including how it releases.
+   `--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`),
+   `shape`, the stack, and the `next` for that stack, including how it releases.
 
    setup scaffolds with `--skip-git`: it composes its own steps and leaves version control to
    you / the enclosing repo, so it does **not** create the scaffold's usual git repo + initial
@@ -246,7 +253,7 @@ and prints the update commands; it changes nothing.
    your summary — if non-zero, read `seed.log` and re-run the seed module manually). Those two
    seed files exist **only when setup started the seed** (attach runs none: only the install
    marker is waited on). When you ran `seed-store.mjs`
-   yourself (connect/iterate runs, reference mode), there is no marker to wait for: the process's
+   yourself (adopt, iterate and published-static runs, reference mode), there is no marker to wait for: the process's
    exit code is the result and its stdout is the JSON — wait on the process (a foreground run,
    or `wait` on its pid), not on a file. Then
    **build & release once** (managed), as the `next` of the `ready_for_brand_layer` event says
@@ -262,7 +269,10 @@ and prints the update commands; it changes nothing.
    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).
+   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
+   recovered from silently, is signal; if anything qualifies, offer to relay it as you deliver the
+   links, and send only after an explicit yes.
 
 ## Reference mode — a static site, or a server-rendered app in another language
 
@@ -277,10 +287,17 @@ close.
 
 ## Verticals
 
+The shortlist. Match the brief against the first column; when it names a Wix product or a
+feature not here, when two rows could fit, or when the request sounds like something this skill
+does not ship (meetings, gift cards, loyalty, groups), read
+`<SKILL_ROOT>/guides/capabilities.md`: every Wix product, what it covers, which vertical here
+ships it and what is not shipped.
+
 | The user wants…                                                                              | Vertical          | Playbook                                   |
 | -------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------ |
 | Online store: products, categories, variants, cart, checkout                                 | **storefront**    | `templates/storefront/INSTRUCTIONS.md`    |
 | Appointments/classes: services, time slots, staff, booking, checkout                         | **bookings**      | `templates/bookings/INSTRUCTIONS.md`      |
+| Rentals: rooms, vehicles, gear rented by the hour or the day, customer-picked length, checkout | **rentals**       | `templates/rentals/INSTRUCTIONS.md`       |
 | Blog: post feed, categories/tags, rich-content post pages                                    | **blog**          | `templates/blog/INSTRUCTIONS.md`          |
 | Structured content collections (directory, recipes, listings) with pages designed per schema | **cms**           | `templates/cms/INSTRUCTIONS.md`           |
 | Any visitor-fillable form: contact/enquiry, signup, application, survey — rendered from the live schema | **forms**         | `templates/forms/INSTRUCTIONS.md`         |
@@ -293,8 +310,10 @@ close.
 | 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
-`node <SKILL_ROOT>/install/deploy.mjs <vertical…>` from the project root before the install
-starts, and run each vertical's seed. A request that matches no shipped vertical has no shipped
-code: it is built from the Wix API reference through `wix-docs` (search, then the method page),
-with the same rule as every other call, on the same project and stack.
+accounts) names them all in the setup call (`--vertical restaurants,blog`), so one install covers
+them; each vertical's seed runs with its own plan. On a project already built,
+`node <SKILL_ROOT>/install/deploy.mjs <vertical…>` from the project root adds one, then one
+`npm install`, then its seed. A request that matches no shipped vertical has no shipped
+code: say so in one line, then build it from the Wix API reference through `wix-docs` (search,
+then the method page), with the same rule as every other call, on the same project and stack,
+starting from the closest shipped vertical when one exists (`guides/capabilities.md` says which).

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, 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."
+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,34 +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. 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.
+**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:
@@ -73,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
 ```
@@ -101,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-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-fast → wix-headless-kit}/guides/migration.md

@@ -1,9 +1,17 @@
 # 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.
+`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
@@ -28,16 +36,19 @@ manages. So:
   `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
+**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 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,
+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.