@wix/agent-skills 1.22.0 → 1.24.0

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

@@ -13,6 +13,7 @@ in the component's `.tsx` and `.module.css`.
 - [Author CSS](#3-author-css)
 - [Wire React](#4-wire-react)
 - [Use Prop-Triggered States on the Root Only](#5-use-prop-triggered-states-on-the-root-only)
+- [Expose Open/Collapsed Toggles](#6-expose-opencollapsed-toggles)
 - [Checklist](#checklist)
 
 ## 1. Choose Supported States
@@ -24,6 +25,7 @@ in the component's `.tsx` and `.module.css`.
 | Other interactive element whose editable focus appearance the user explicitly requests | `focus` |
 | Disableable — `button`/`input`/`select`/`textarea`/`fieldset` or a disableable role | `disabled` (+ `invalid` for `input`/`select`/`textarea`) |
 | Has a selectable/variant value in its data — `selected`/`active`/`current`/`open`/`expanded`/`checked`/`featured` | that custom state |
+| Whole component opens/collapses (expandable panel, disclosure, dropdown, drawer), even when a click toggles it | root `isOpen` prop state — see §6 |
 | None of the above | no states — resting style only |
 
 An explicit `role` overrides the tag's implicit semantics: `<input role="button">`
@@ -51,7 +53,10 @@ nested (`card__row--selected`).
 ## 3. Author CSS
 
 Put the resting value in the bare class; put only the state override in the
-state selector.
+state selector. When both set the same property, write the state selector
+**before** the bare class. Manifest generation can otherwise record the state
+value as the part's resting `defaultValue`, even though runtime CSS renders
+correctly. The state selector still wins at runtime through its specificity.
 
 - **Native design state** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
@@ -63,17 +68,22 @@ state selector.
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
 state class is the **prefixed** global one.
 
+Check text contrast against every background it appears on, including resting,
+hover, and selected states. Normal text needs at least 4.5:1; large text needs
+3:1. Pale gray small text on white or a tinted selected row commonly fails.
+The local static accessibility scan cannot measure rendered color contrast.
+
 ```css
+.cta:global(.pricing-card-cta--hover),
+.cta:hover {
+  background: #4f46e5;
+}
 .cta {
   background: #6366f1;
   font-family: 'Inter', sans-serif;
   font-size: 14px;
   color: #ffffff;
 } /* resting */
-.cta:global(.pricing-card-cta--hover),
-.cta:hover {
-  background: #4f46e5;
-}
 .cta:global(.pricing-card-cta--disabled),
 .cta:disabled {
   opacity: 0.5;
@@ -91,7 +101,9 @@ state class is the **prefixed** global one.
 - **Native** — render the correct interactive element (`<button>`, an
   interactive `role`, or a handler). No custom state class is needed, but the
   element must still satisfy the accessibility contract for its semantics.
-- **Custom** — toggle the global state class from the element's data.
+- **Custom** — toggle the global state class from the element's data. Every
+  state class toggled in TSX needs a matching `:global()` rule in §3; without
+  one the manifest generator silently drops the state.
 - **Inner elements** — every named inner element gets an `elementProps` entry;
   spread it so editor-driven states reach it. On a raw HTML element also merge
   `elementProps?.<key>.className` inline; on a skill-built sub-component the
@@ -155,8 +167,9 @@ Rules:
   `props: { isFeatured: true }` as the trigger.
 - To give the state styling, pair the root's **module** class with a prefixed
   `:global(.<component-name>--<state>)` rule. With a matching class the manifest
-  entry carries that `className`; with none it is props-only (the editor still
-  toggles the prop, but nothing restyles).
+  entry carries that `className` and the editor lists it with the design-panel
+  states; with none it is props-only and appears in the on-stage state picker,
+  which sets the prop. An open/collapsed toggle must stay props-only (§6).
 
 ```css
 .pricingCard:global(.pricing-card--is-featured) {
@@ -166,7 +179,48 @@ Rules:
 
 Prefer a native state (interactive markup) or a class trigger (per-item data
 such as `row.selected`) whenever one fits — those are the common cases and work
-at any depth. Reach for a prop trigger only for a root-level boolean switch.
+at any depth. Reach for a prop trigger only for a root-level boolean switch
+or an open/collapsed toggle (§6).
+
+## 6. Expose Open/Collapsed Toggles
+
+For a component that opens or collapses, expose its state to the editor even
+when a click toggles it. `useState` alone gives the manifest no state picker.
+For one-of-many item bodies, use the active-item contract instead.
+
+- Add `isOpen?: ElementState<boolean>` and set `isOpen: false` in
+  `defaultProps`.
+- Seed and resync internal state from the prop; clicks update internal state.
+- Always render the collapsible content; hide it with CSS plus `aria-hidden`
+  and `inert` when closed. Never mount it with `open && …`.
+- Style the open state with inner-part classes
+  (`<component-name>-content--open`) and matching `:global()` rules, not only
+  inline styles or refs measured during render.
+- Keep the root state props-only for the on-stage picker (§5).
+
+```tsx
+const [open, setOpen] = React.useState(Boolean(isOpen));
+React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
+
+<div
+  {...elementProps?.content}
+  aria-hidden={!open}
+  {...(!open && { inert: '' })}
+  className={classNames(
+    'info-panel-content',
+    styles.content,
+    open && 'info-panel-content--open',
+    elementProps?.content?.className,
+  )}
+>
+  <p>{text}</p>
+</div>
+```
+
+```css
+.content { display: none; }
+.content:global(.info-panel-content--open) { display: block; }
+```
 
 ## Checklist
 
@@ -176,4 +230,7 @@ at any depth. Reach for a prop trigger only for a root-level boolean switch.
 - [ ] Non-input controls retain a standalone `:focus-visible` keyboard indicator.
 - [ ] Custom state classes are flat, global, and prefixed by component and part.
 - [ ] Named inner parts spread and merge their `elementProps` entry.
+- [ ] Every state class toggled in TSX has a matching `:global()` CSS rule.
 - [ ] `ElementState<boolean>` is used only for a component-level root state.
+- [ ] An open/collapsed component exposes a props-only `isOpen` root state,
+      syncs internal state from it, and always renders its content.

package/skills/wix-app/references/editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md

@@ -9,12 +9,17 @@ generation rewrites
 For a new component, complete the scaffolded installation and layout fields.
 For an existing component, change only the sizing, installation, or manifest
 behavior requested by the user; preserve every other extension field.
+Use the current scaffold's field shape and the values below. Inspect installed
+`@wix/astro` or schema types only if a related typecheck or build error requires it.
+Normal component setup needs no `ELEMENT_TYPE` or `DATA_TYPE` lookup: the
+generated `editorElement` and props manifest supply those details.
 
 ## Contents
 
 - [Preserve the Extension Shape](#preserve-the-extension-shape)
 - [Choose Initial Height](#choose-initial-height)
 - [Choose Resize Direction](#choose-resize-direction)
+- [Values](#values)
 - [Checklist](#checklist)
 
 ## Preserve the Extension Shape
@@ -53,6 +58,12 @@ should fit content, use `content`.
 
 Allow an axis only when dragging it produces a meaningful result.
 
+For each allowed axis, implement what happens when content no longer fits.
+Content height must grow after wrapping or changing items. A bounded height
+needs a fitting layout or a deliberate accessible scroll region. Installation
+defaults alone do not prevent overflow after resizing. Do not rely on native
+container overflow controls for a custom component's internal DOM.
+
 | Value | Use when |
 | --- | --- |
 | `horizontalAndVertical` | Content meaningfully fills both axes; default for framed visuals and most layouts |
@@ -61,11 +72,25 @@ Allow an axis only when dragging it produces a meaningful result.
 | `aspectRatio` | Distortion would break the component's identity |
 | `none` | A parent fully owns size; do not use for a top-level component |
 
+## Values
+
+Every value the scaffold uses comes from `LAYOUT` in
+`@wix/react-component-schema`; do not search `node_modules` for them.
+
+| Field | Values |
+| --- | --- |
+| `layout.resizeDirection` (`LAYOUT.RESIZE_DIRECTION`) | `horizontal`, `vertical`, `horizontalAndVertical`, `aspectRatio`, `none` |
+| `layout.contentResizeDirection` (`LAYOUT.CONTENT_RESIZE_DIRECTION`) | `horizontal`, `vertical`, `horizontalAndVertical`, `none`: the axes along which content growth resizes the component |
+| `initialSize.{width,height}.sizingType` (`LAYOUT.SIZING_TYPE`) | `content`, `pixels`, `stretched` |
+| `installation.staticContainer` | `'HOMEPAGE'`, `'GLOBAL_PAGE'` |
+
 Edit the scaffolded `layout`, `installation`, and `resources` fields in place;
 do not reconstruct the extension from an example. For a new component, add
 `staticContainer: 'HOMEPAGE'`. For an existing component, preserve its current
 `staticContainer` value unless the request explicitly changes installation
 behavior.
+The scaffold's `installation` object accepts `staticContainer` next to
+`initialSize`; add the literal above without searching `@wix/astro` types.
 
 ## Checklist
 

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). Triggers: build me a store/blog/booking/event/restaurant/portfolio site fast, take appointments fast, sell tickets or membership plans headless, wix headless fast, connect a Wix business app with ready-made SDK code."
+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
@@ -74,7 +74,13 @@ doesn't express — or once the site exists and the work turns to managing or ex
   `capabilities.mediaUpload.policies` entry to the plan; Fast ships its client helper, Astro
   endpoint, dependencies, and generated policy module once. Read
   `templates/shared/CUSTOM_OPERATIONS.md` before choosing it. The agent wires the helper to
-  the product UI; it never authors or widens the endpoint.
+  the product UI; it never authors or widens the endpoint. For a site-wide search (a header box
+  with suggestions, a `/search?q=` page over the deployed verticals' products, services, posts
+  and events), add a `capabilities.siteSearch` entry; Fast ships its data layer, stores, hooks,
+  components and search page once. Enabling it means the Wix Site Search app is installed on the
+  site by the seed step (`install: true`; the capability's `seed/install.mjs`, run after the
+  content seed) — the index fills within about half a minute of the install. Playbook:
+  `templates/shared/capabilities/site-search/INSTRUCTIONS.md`.
 
 ## The run
 
@@ -83,9 +89,26 @@ Needed throughout: Node ≥ 20.11, git, a logged-in Wix CLI (`npx @wix/cli@lates
 read tokens into context), and the two companion skills beside this one, `wix-docs` and
 `wix-manage` (if `.agents/skills/` lacks them:
 `CI=1 npx skills@latest add wix/skills --skill wix-docs --skill wix-manage --yes`). The cold-start
-page, `cold-start/cold-start.md`, gets a machine with none of this to that point. Then fetch the shipped
+page, `cold-start/cold-start.md`, gets a machine with none of this to that point. In a folder that
+already holds a `wix.config.json`, `node <SKILL_ROOT>/install/context.mjs` first: it runs
+`wix env pull` when `.env.local` is missing and prints the 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
@@ -128,52 +151,58 @@ the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
      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 is read from the config), then ONE
-     `npm install`, then the seed module if there is content to create. A project this skill
-     built needs only the first, for a new solution; a change to what is built is file edits
-     and a release.
-   - **`wix.config.json` and no project** (what `init` leaves in an empty folder) → the site
-     exists and has no frontend yet: `attach.mjs` (below), which takes the site from the config,
-     reuses its hosting, scaffolds and deploys. No seed: the site owns its content.
+   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
@@ -224,7 +253,7 @@ the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
    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
@@ -235,9 +264,15 @@ the `templates/…` paths below are relative to `<SKILL_ROOT>`, where it lands.
    build+release mid-flow; backend content is fetched at
    runtime, so a re-release never "refreshes" seeded data. The run is complete only when the
    site is released — close with the live URL and the dashboard link
-   `https://manage.wix.com/dashboard/<siteId>`. **Copy the live URL verbatim from the
+   `https://manage.wix.com/dashboard/<siteId>` (the `siteId` of the `ready_for_brand_layer`
+   event: on a migration preview that is the migrated site's dashboard, the release URL is the
+   preview's, the original site is unchanged, and completing the migration is the user's next
+   step in the Wix CLI once they approve — say all three). **Copy the live URL verbatim from the
    `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
-   a 404).
+   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
 
@@ -252,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`         |
@@ -264,10 +306,14 @@ close.
 | Portfolio/showcase: collections of projects, project pages with media galleries              | **portfolio**     | `templates/portfolio/INSTRUCTIONS.md`     |
 | Membership/subscription plans: pricing page, plan detail, hosted purchase                    | **pricing-plans** | `templates/pricing-plans/INSTRUCTIONS.md` |
 | Restaurant: menu with photos, online ordering, table reservations                            | **restaurants**   | `templates/restaurants/INSTRUCTIONS.md`   |
+| FAQ: questions grouped by category, search, expandable answers, a link per question         | **faq**           | `templates/faq/INSTRUCTIONS.md`           |
+| Donations: campaign pages, goal progress, one-time and recurring giving via hosted checkout   | **donations**     | `templates/donations/INSTRUCTIONS.md`     |
 
 Verticals compose: a brief that spans several (a restaurant with a blog, a store with member
-accounts) deploys them together — setup takes one vertical; deploy the rest with
-`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).