@wix/agent-skills 1.23.0 → 1.24.0

package/skills/wix-app/references/editor-react-component/OVERFLOW.md

@@ -0,0 +1,146 @@
+# Overflow and Resizing
+
+Apply when creating a component or changing its layout, content, or sizing.
+Custom components own their internal layout; do not assume the editor exposes
+native-container overflow settings for their DOM. The component must keep
+content and controls usable within its assigned size.
+
+## Choose What Happens When Content Does Not Fit
+
+- **Content-height component:** reflow at narrower widths and let normal-flow
+  content establish height. Do not constrain it with `height: 100%`, a fixed
+  height, or absolute positioning of all content.
+- **Bounded-height component:** propagate the height constraint through growing
+  wrappers (`min-height: 0` for flex/grid items). Fit the content or give the
+  intended content region `overflow: auto`; keep essential controls reachable.
+  Choose scrolling only when it suits the requested interaction.
+- **Carousel or other intentional overflow:** contain the oversized track in
+  its own viewport and provide working navigation/scrolling to every item.
+  Treat a requested count such as "show four items at a time" as the
+  default/initial-width presentation unless the user explicitly requires that
+  column count at every width. Each carousel page should still contain that
+  requested group at narrow widths, but its internal layout must reflow so every
+  required item is usable. Stacking or wrapping the current page's items
+  preserves the group; squeezing them into tiny columns or clipping later items
+  does not. Choose the installation width, gaps, padding, and usable item
+  minimum together so the requested count actually fits at the initial size.
+
+  A container-driven group page can preserve the requested grouping without
+  changing the carousel's item-count logic:
+
+  ```css
+  .trackViewport {
+    min-width: 0;
+    overflow: hidden;
+  }
+
+  .page {
+    box-sizing: border-box;
+    display: grid;
+    flex: 0 0 100%;
+    min-width: 0;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr));
+    gap: 16px;
+  }
+
+  .item {
+    min-width: 0;
+  }
+  ```
+
+  At a wide initial width, the page uses the requested presentation count. When
+  the component is narrower than a usable item minimum, the same group wraps to
+  fewer columns or a single column and its content-height component grows.
+  Equivalent container-query or wrapping layouts are valid. A fixed
+  `repeat(<count>, minmax(0, 1fr))` or percentage basis derived from the count is
+  not sufficient as the only layout for a horizontally resizable component.
+
+Do not apply blanket `overflow: hidden`/`clip` to the root or page as a repair.
+It can hide text, focus indicators, navigation, and overlays while leaving the
+layout defect intact. Clip a dedicated media/track/decorative region only when
+that is its intended behavior. Preserve deliberate shadows and overlays.
+
+## Remove Intrinsic Sizing Traps
+
+`width: 100%` and `box-sizing: border-box` on the root are necessary, but do not
+constrain descendants. A bare `1fr` track has an automatic minimum; three such
+tracks can exceed the container even when the grid itself is correctly sized.
+
+- Use `min-width: 0` on flex/grid items that must shrink, including nested
+  content wrappers. For a fixed column count, use `minmax(0, 1fr)`; still adapt
+  the layout when columns would become too narrow to use.
+- Prefer fewer columns or wrapping to squeezing text and controls. An intrinsic
+  collection can use the following pattern; the minimum never exceeds its
+  container's content width:
+
+  ```css
+  .grid {
+    box-sizing: border-box;
+    display: grid;
+    min-width: 0;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
+    gap: 16px;
+  }
+  ```
+
+  `minmax(280px, 1fr)` alone still overflows a slot narrower than 280px.
+  This grid is suitable for a wrapping collection, not a substitute for a
+  carousel's item/navigation contract.
+- For user-authored prose, allow wrapping and use `overflow-wrap: anywhere`
+  where long words/URLs could force intrinsic width. Use truncation only when
+  the product intends it and essential content remains available.
+- Constrain images/media to the space available; preserve aspect ratio or use
+  an intentional fitted media frame. Check fixed-size media plus adjacent text,
+  padding, borders, and gaps together.
+- Let control rows and pagination adapt without losing buttons, focus rings,
+  or usable target sizes. `min-width: 0` does not make fixed children or large
+  padding fit by itself.
+
+Adapt to the component's width, including a narrow slot on a desktop viewport.
+Do not derive the layout from `window.innerWidth` or viewport breakpoints. If
+container queries are needed, establish the query container on an appropriate
+ancestor; a query cannot restyle its own container based on that container's
+size. Do not add size containment on an auto-height component that prevents
+content from establishing its height.
+
+## Review Before Reporting Completion
+
+First inspect the sizing chain in source. Identify the root, growing wrappers,
+tracks, cards, text, media, and controls; check each constrained axis. Do not
+infer safety from a CSS keyword or a successful build.
+
+When a runnable browser preview is available, exercise the actual component:
+
+1. Vary the **component container** independently of the page viewport. Cover
+   its initial size, 320px, a narrower stress probe such as 240px, and a wider
+   slot. For a vertically resizable component, also test a short bounded height;
+   for content height, verify the root grows without overlapping the next block.
+   A horizontally resizable top-level component must keep required content
+   usable at 320px unless an actual supported editor minimum is part of its
+   contract. Treat 240px as a stress probe. Report any unsupported size and its
+   remaining usability limit.
+2. Use long prose and an unbroken token, larger text, changed padding/borders,
+   and representative item counts. For carousels, test navigation and the
+   longest item; include RTL when direction changes layout or navigation.
+3. Compare root/region `scrollWidth` with `clientWidth` (allow about 1px for
+   rounding), and inspect descendant bounds. For bounded height, also compare
+   `scrollHeight` and `clientHeight`. An intentional scroll region/track may
+   exceed its client size, but its content must remain reachable and contained.
+   Check the component itself: a page ancestor may clip overflow while the
+   document has no horizontal scrollbar. Conversely, shadows/overlays do not
+   automatically mean the content layout is broken.
+4. Visually inspect and use the controls/keyboard. Passing geometry checks by
+   clipping required content is a failure. Verify intentional scroll regions
+   are usable with keyboard and touch, focus stays visible, and navigation can
+   reach every item.
+
+Fix confirmed component-owned defects and repeat affected cases. If the first
+incorrect constraint comes from the host layout, report that boundary instead
+of masking it inside the component. For existing components, preserve unrelated
+public props, editor overrides, and behavior.
+
+Report sizes/states tested and any remaining overflow or inaccessible content.
+If no browser preview or fixture is available, perform the source review and
+state that rendered resize behavior is **unverified**; do not claim the resize
+review passed. Build, typecheck, a11y scans, and manifest generation do not
+establish that layout fits.

package/skills/wix-app/references/editor-react-component/PARTS.md

@@ -45,6 +45,12 @@ Apply this filter to every candidate:
   share the same semantic editor surface. Distinguish position with data or a
   module-only helper class, not separate part names.
 
+The manifest generator can silently omit a named part behind conditional JSX.
+Keep an editor-controlled part mounted in the render it inspects. Hide it with
+CSS driven by a data attribute, or disable it when it should remain visible.
+After generating the manifest, confirm that its `elements` include every
+intended named part.
+
 ## Sanity Check
 
 For each candidate, ask:

package/skills/wix-app/scripts/scan-a11y-eslint.cjs

@@ -40,7 +40,9 @@ const RULE_CONFIG = {
   'jsx-a11y/no-noninteractive-element-to-interactive-role': 'error',
   // A tabpanel with no focusable content takes tabIndex=0 (ARIA Authoring Practices).
   'jsx-a11y/no-noninteractive-tabindex': ['error', { roles: ['tabpanel'] }],
-  'jsx-a11y/no-redundant-roles': 'error',
+  // Safari drops <ul> list semantics with list-style: none; role="list" restores
+  // them (WebKit bug 170179). Keep all other redundant roles flagged.
+  'jsx-a11y/no-redundant-roles': ['error', { ul: ['list'] }],
   'jsx-a11y/no-static-element-interactions': 'error',
   'jsx-a11y/prefer-tag-over-role': 'error',
   'jsx-a11y/role-has-required-aria-props': 'error',
@@ -74,6 +76,22 @@ function forwardsOnlySdkHandlers(tag) {
   );
 }
 
+const PASSIVE_AUTOPLAY_HANDLERS = new Set([
+  'onMouseEnter',
+  'onMouseLeave',
+  'onFocus',
+  'onBlur',
+  'onFocusCapture',
+  'onBlurCapture',
+]);
+
+/** Carousel roots observe hover/focus to pause autoplay; these handlers do not activate the region. */
+function pausesAutoplayOnly(tag) {
+  if (!isSdkRoot(tag) || !tag.includes('data-pause-button-visibility=')) return false;
+  const handlers = [...tag.matchAll(/\b(on[A-Z]\w*)=\{[^}]*\}/g)];
+  return handlers.length > 0 && handlers.every(([, name]) => PASSIVE_AUTOPLAY_HANDLERS.has(name));
+}
+
 /** Roles whose native element cannot express a styled component. */
 const ROLES_WITHOUT_NATIVE_TAG = new Set(['img', 'presentation', 'none', 'group', 'status']);
 
@@ -93,6 +111,12 @@ function roleHasNoNativeTag(tag) {
  * `rules` is skipped when the opening tag of the reported element matches `tag`.
  */
 const EXEMPTIONS = [
+  {
+    // ANIMATED-COMPONENTS.md requires the noninteractive carousel root to
+    // observe hover and focus so autoplay stops while a visitor is using it.
+    rules: new Set(['jsx-a11y/no-noninteractive-element-interactions']),
+    tag: pausesAutoplayOnly,
+  },
   {
     // SDK handlers (`onClick`, `onMouseIn`, ...) are forwarded on the root
     // element, which carries `id={id}`; the root itself is not the control.

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
@@ -91,17 +91,25 @@ read tokens into context), and the two companion skills beside this one, `wix-do
 `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
 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.)