@wix/agent-skills 1.23.0 → 1.25.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/SKILL.md

@@ -9,7 +9,6 @@ allowed-tools:
   - Bash(npm install *)
   - Bash(npm run *)
   - Bash(node *)
-  - Bash(bash *)
   - Bash(cd *)
   - Bash(ls *)
   - Bash(mkdir *)

package/skills/wix-headless/references/CAPABILITIES.md

@@ -67,7 +67,7 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 
 ### bookings — appointments and classes
 - **Intent:** book / appointment / schedule / class / session / reserve a slot — a **service or appointment with a provider** (a stylist, trainer, tutor, clinic, studio).
-- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a wine tasting, cheese pairing, chef's table, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
+- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a chef's table, cheese pairing, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
 - **Not bookings — route to `rentals` instead:** when the **customer chooses how long** they want something, and what's booked is a **thing rather than a person** — a room by the hour, a desk for three days, a van for the weekend. The tell is a duration *range* the customer picks within. A 60-minute haircut is `bookings`; a meeting room booked for 1–8 hours is `rentals`.
 - **Required site features:** a list of services; a page per service; a way to pick a time and book it.
 - **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
@@ -85,8 +85,8 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **Implementation checklist:** show each plan's name, price, and billing cycle; list what each plan includes (the perks); a clear "choose plan" action; highlight a recommended tier where it makes sense.
 
 ### restaurants — menus and food
-- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (wine tasting, cheese pairing, chef's table, tasting-menu evening).
-- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a wine-and-cheese pairing), which ride on the Table Reservations app.
+- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (chef's table, cheese pairing, tasting-menu evening).
+- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a chef's table), which ride on the Table Reservations app.
 - **Experiences vs bookings — decide here:** an **experience** is a **reservation that is itself a special dining occasion at the restaurant** — it books seats at the restaurant's own location and carries its own name, per-guest price, schedule, and booking form. Use it for pairing sessions, tastings, and chef's tables. Use the separate **`bookings`** vertical only for a **service/appointment/class with a provider** that isn't a seat at the restaurant. For anything a restaurant hosts and seats, prefer an experience.
 - **Implementation checklist:** show the menu grouped into sections in order; each item's name, description, price, and labels (vegan, spicy…) and modifiers / variants where they exist; an order action if online ordering is wired; a reserve-a-table action if reservations are wired; **if experiences are wired, list each experience with its name, description, per-guest price, and schedule, and a reserve-seats action.**
 

package/skills/wix-headless/references/DISCOVERY.md

@@ -52,7 +52,7 @@ For each capability, build its `intent.<cap>` block — the inputs the seed step
 | bookings | `{ serviceCount, servicesNamed: [] }` | `serviceCount: 2`, brand-derived service names |
 | rentals | `{ unitType, serviceCount, resourceCount, servicesNamed: [] }` | `unitType: "HOUR"` (`"DAY"` if the brief rents by the day), `serviceCount: 2`, `resourceCount: 2`, brand-derived item names |
 | pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
-| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (wine/cheese pairing, chef's table) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
+| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (chef's table, tasting menu) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
 | portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
 
 Counts are deliberately small (the seed shows the shape, not a full catalog).

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -48,7 +48,7 @@ Before implementing a capability, Read the local recipe linked in its row.
 | restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
 | portfolio | `@wix/portfolio` (+ `media` from `@wix/sdk` to resolve image strings; **no** `@wix/ecom`/`@wix/redirects` — display-only) | `how-to-code-portfolio.md` — Portfolio v1 display-only read. |
 | restaurants — table reservations (add-on; only when the Table Reservations app is in the run) | `@wix/table-reservations` (a **distinct** package from `@wix/restaurants`; **no ecom/redirects** — a reservation is a hold, not a purchase) | `how-to-code-restaurant-reservations.md` — book-a-table hold→reserve. |
-| restaurants — experiences (add-on; special dining occasions guests reserve — wine/cheese pairing, chef's table) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
+| restaurants — experiences (add-on; special dining occasions guests reserve — chef's table, tasting menu) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
 
 > **Cross-cutting packages** (`CAPABILITIES.md` § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If **coupons** were seeded, add `@wix/marketing`. The eCommerce checkout packages (`@wix/ecom`, `@wix/redirects`) are already folded into the stores row above — include them once when any purchase-flow vertical is present.
 

package/skills/wix-headless/references/SEED.md

@@ -39,7 +39,7 @@ Each entry states only the entities, where their count/content comes from, the p
 - **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
 - **rentals** — *Rentable resources.* Recipe: **`setup-rentals.md`**. A resource **type** per kind of thing rented (rooms, vans, cameras), then `intent.rentals.resourceCount` **resources** inside it (Room A / Room B — parallel capacity comes from more resources, not higher capacity), then `intent.rentals.serviceCount` **rental services**, each carrying the Wix Rentals `appId`, `serviceResources` naming its resource type, a `primaryResourceType`, and a `durationRange` (`HOUR` or `DAY`) with the min/max the request implies — defaulting to **60/480 minutes** hourly and **1/5 days** daily when the brief doesn't say — and a **per-unit** price. **No category** — unlike bookings, rental services don't use one; don't create or assign one. **Order is load-bearing: resource type → resources → services** — a service whose resource type holds no resources has permanently empty availability. Seed resources **24/7** (no working-hours schedule) unless the request names opening hours; that keeps a multi-day rental to a single booking. **Keep:** `resourceTypeIds[]` as seed-time state (services key on them); nothing for the handoff — rentals are discovered **live** (`queryServicesByFilters` filtered by the rentals `appId`).
 - **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).
-- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Configure the business-location address (`setup-restaurant-orders.md` STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks.** If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a *paid* order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); **configure the business-location address (`setup-restaurant-reservations.md` STEP 0)** — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently. **Experiences (add-on within Table Reservations, on demand)** — only when the request names **special dining occasions guests reserve** (wine/cheese pairing, chef's table, tasting-menu evening — an *experience*, not a `bookings` service; see `CAPABILITIES.md`): they need the **Table Reservations app** (no extra install) and a configured **business-location address** (`setup-restaurant-reservations.md` STEP 0, same as reservations) and, unlike plain reservations, they **are** seeded — create one Experience per named occasion on the default reservation location, following **`setup-restaurant-experiences.md`**. Booking an experience is **premium-gated** like online reservations (record the precondition, don't fail). **Keep:** nothing for the handoff — experiences are read **live** (`queryExperiences`); track `experienceId`(s) transiently.
+- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Configure the business-location address (`setup-restaurant-orders.md` STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks.** If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a *paid* order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); **configure the business-location address (`setup-restaurant-reservations.md` STEP 0)** — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently. **Experiences (add-on within Table Reservations, on demand)** — only when the request names **special dining occasions guests reserve** (chef's table, tasting menu, tasting-menu evening — an *experience*, not a `bookings` service; see `CAPABILITIES.md`): they need the **Table Reservations app** (no extra install) and a configured **business-location address** (`setup-restaurant-reservations.md` STEP 0, same as reservations) and, unlike plain reservations, they **are** seeded — create one Experience per named occasion on the default reservation location, following **`setup-restaurant-experiences.md`**. Booking an experience is **premium-gated** like online reservations (record the precondition, don't fail). **Keep:** nothing for the handoff — experiences are read **live** (`queryExperiences`); track `experienceId`(s) transiently.
 - **portfolio** — *A project showcase.* Recipe: **`setup-portfolio.md`**. Create the `intent.portfolio.collections` (title + short description fitting `brand`), then `intent.portfolio.projectCount` projects assigned to them — **collections before projects** (a project's `collectionIds` must hold real collection ids; see the recipe). Text-only by default (omit `coverImage`; images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `collectionIds{<name>}` to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects **live** (`collections.queryCollections` / `projects.queryProjects`), so owner-added content appears with no code change.
 
 > **Cross-cutting (on demand).** `coupons` is not a standalone capability (`CAPABILITIES.md` § "Cross-cutting capabilities") — there's no app to install and it's not in `verticals[]`. If intent calls for discounts **and** a parent vertical (stores / bookings / events / pricing-plans) is in this run, create coupons scoped to that parent and add the coupon to the `seeded` map (`seeded.coupons = { couponIds[] }`). **Coupons has no inline recipe** — read the create shape from the docs (`DOC_DISCOVERY.md` is the fallback): every coupon needs a scope with a namespace and its parent vertical's app installed (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/about-wix-coupons.md>), and the create-coupon spec needs name/code/start + a scope namespace + exactly one coupon-type field (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/create-a-coupon.md>). eCommerce needs no seeding — it's the runtime checkout layer that rides along.

package/skills/wix-headless/references/SETUP.md

@@ -25,7 +25,7 @@ For each capability in `verticals[]`, install its app by `appDefId` (these are t
 - **bookings** → `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
 - **rentals** → `ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e` (Wix Rentals). Rentals provisions the Bookings infrastructure it runs on, so a Rentals-only install is enough — its availability comes back without adding Wix Bookings separately. Rentals has **no APIs of its own**: it is Services V2 with rentals-specific field values (`setup-rentals.md`), and its frontend package is `@wix/bookings` — there is no `@wix/rentals`. Rentals uses no categories; to also offer plain fixed-duration services, install Wix Bookings (`13d21c63-b5ec-5912-8397-c3a5ddb27a97`) as well, seed those with `setup-bookings.md`, and filter every catalog read by `appId` so the two sets stay separate.
 - **pricing-plans** → `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`
-- **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — wine tastings, chef's tables; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
+- **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — chef's tables, tasting menus; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
 - **portfolio** → `d90652a2-f5a1-4c7c-84c4-d4cdcc41f130` (Wix Portfolio; the install ships a default sample collection + projects — `setup-portfolio.md` STEP 0 cleans them)
 - **cms** → **no install** (Wix Data is core) — skip
 

package/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-reservations.md

@@ -166,7 +166,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/rese
 
 ### Booking an experience (only when experiences are in the run)
 
-An **experience** is a reservation that *is* a curated dining occasion (wine/cheese pairing, chef's table). It uses the **same** booking mechanism as a table, with two differences: you **list experiences** to show and choose from, and you offer bookable times **projected from the experience's own schedule** (there is *no* experience-scoped slot API — see Gotcha C) rather than from `getScheduledTimeSlots`, then stamp the chosen `experienceId` onto the reservation. Read the shapes from the docs (`.md?apiView=SDK`); the earned drift gotchas below are what the docs won't tell you.
+An **experience** is a reservation that *is* a curated dining occasion (chef's table, tasting menu). It uses the **same** booking mechanism as a table, with two differences: you **list experiences** to show and choose from, and you offer bookable times **projected from the experience's own schedule** (there is *no* experience-scoped slot API — see Gotcha C) rather than from `getScheduledTimeSlots`, then stamp the chosen `experienceId` onto the reservation. Read the shapes from the docs (`.md?apiView=SDK`); the earned drift gotchas below are what the docs won't tell you.
 
 Flow (mirrors the docs' sample flow — <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/sample-flows.md>):
 

package/skills/wix-headless/references/inline-recipes/setup-restaurant-experiences.md

@@ -1,6 +1,6 @@
 ---
 name: "Setup Restaurant Experiences"
-description: Seeds Wix Table Reservations **Experiences** — a reservation that IS a special dining occasion at the restaurant (wine tasting, cheese pairing, chef's table, tasting-menu evening), as opposed to a plain table booking or a Bookings service. Points to the live docs for the full create payload and carries only the earned gotchas the docs don't state (field-shape drift, payment policy, premium gating, when-to-use). The occasions/prices/schedule come from the request.
+description: Seeds Wix Table Reservations **Experiences** — a reservation that IS a special dining occasion at the restaurant (chef's table, cheese pairing, tasting-menu evening), as opposed to a plain table booking or a Bookings service. Points to the live docs for the full create payload and carries only the earned gotchas the docs don't state (field-shape drift, payment policy, premium gating, when-to-use). The occasions/prices/schedule come from the request.
 ---
 **RECIPE**: Business Recipe – Experiences Setup for Wix Table Reservations (Experiences API)
 
@@ -8,7 +8,7 @@ description: Seeds Wix Table Reservations **Experiences** — a reservation that
 
 ## When to use experiences (and when NOT to)
 
-An **experience** is a **reservation that is itself a curated dining occasion at the restaurant** — it books seats at the restaurant's own reservation location but overrides the location's defaults with its own name, description, per-guest payment policy, party-size, schedule, and booking form. Reach for it when the brief names a **wine tasting, cheese/wine pairing, chef's table, or tasting-menu evening**.
+An **experience** is a **reservation that is itself a curated dining occasion at the restaurant** — it books seats at the restaurant's own reservation location but overrides the location's defaults with its own name, description, per-guest payment policy, party-size, schedule, and booking form. Reach for it when the brief names a **chef's table, cheese pairing, or tasting-menu evening**.
 
 - **Experience vs plain reservation:** a plain reservation just books a table; an experience books a *named, scheduled, often paid occasion*. Same booking mechanism, different intent.
 - **Experience vs `bookings`:** the separate `bookings` vertical is for a **service/appointment/class with a provider** (spa, tutor, studio). If a restaurant *hosts and seats* the occasion, it's an experience — not a booking. (See `CAPABILITIES.md` — "Experiences vs bookings".)

package/skills/wix-headless/references/managed/AUTHENTICATION.md

@@ -16,7 +16,7 @@ npx @wix/cli@latest whoami   # exits 0 when logged in; non-zero when logged out
 If it's non-zero, **log in yourself** — don't punt to the user and stop. A foreground command that exits in seconds, one JSON event per line:
 
 ```bash
-node ../../entry/bootstrap.mjs   # path relative to this file
+node ../../scripts/bootstrap.mjs   # path relative to this file
 ```
 
 | Event | Do |
@@ -25,20 +25,9 @@ node ../../entry/bootstrap.mjs   # path relative to this file
 | `awaiting_user` (`verificationUri`, `userCode`, `message`) | Send `message` verbatim, then stop. Re-run the script when the user says they're done → `logged_in`. Re-running early returns the **same** code, not a new one. |
 | `cli_unreachable` / `login_failed` (`detail`) | Show `detail` and stop. |
 
-### If you'd rather not execute it
+### What the script does
 
-Read `../../entry/bootstrap.mjs` and do the same thing yourself. What matters:
-
-```bash
-# AI_AGENT must be set, or the CLI renders an interactive Ink TUI and emits no JSON.
-# Detach, redirecting to a FILE — a pipe dies with your process and the CLI gets EPIPE.
-AI_AGENT=my-agent nohup npx -y @wix/cli@latest login > /tmp/wix-login.log 2>&1 &
-
-grep -m1 awaiting_user /tmp/wix-login.log
-# {"event":"awaiting_user","expiresInSeconds":600,"userCode":"…","verificationUri":"…"}
-```
-
-Send the user that URL + code, then stop — nothing moves until they act. The detached login lands the session on its own; resume with `whoami` (exit 0). Codes last ~10 min; after that, start a new login and surface the new code.
+Read `../../scripts/bootstrap.mjs` if you want to see it: it sets `AI_AGENT` so the CLI emits JSON events instead of an interactive TUI, starts `wix login` detached with its output in a file under the OS temp dir (a pipe would die with the parent), and prints the device code. It is the one login path; there is no manual variant. Codes last ~10 min; after that, run it again and surface the new code.
 
 ## 2 · Mint the token
 

package/skills/wix-headless/scripts/bootstrap.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ── tiny event protocol (one JSON object per line) ───────────────────────────
+const emit = (event, extra = {}) =>
+  process.stdout.write(JSON.stringify({ event, ...extra }) + '\n');
+const fail = (event, extra = {}) => {
+  emit(event, { ok: false, ...extra });
+  process.exit(1);
+};
+
+// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
+const isWin = process.platform === 'win32';
+const bin = (name) => (isWin ? `${name}.cmd` : name);
+const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
+
+// Force the CLI into non-interactive "agent" mode. Without an agent signal in
+// the env, `wix login` renders an interactive Ink TUI (device code + keypress)
+// that needs a raw TTY and crashes in an agent sandbox — and it never emits the
+// JSON login events this script forwards. The CLI uses @vercel/detect-agent,
+// 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-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-login');
+const LOG = join(STATE_DIR, 'login.log');
+const PIDFILE = join(STATE_DIR, 'login.pid');
+
+// run a command, capture stdout+stderr (combined), return {status, out}
+function capture(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
+  return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
+}
+
+// ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
+function checkCli() {
+  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
+  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
+  // npx interleaves "npm notice …" lines with the version, so don't just take the
+  // last line — pick the first semver-looking token, falling back to the last line.
+  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
+  emit('cli_ok', { version });
+}
+
+// ── 2. Reuse an existing session, or start device login ──────────────────────
+const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
+
+function loginEvents() {
+  if (!existsSync(LOG)) return [];
+  return readFileSync(LOG, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null; // non-JSON CLI chatter
+      }
+    })
+    .filter((e) => e && e.event);
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// A login this machine started earlier may still be waiting on the browser. Reuse
+// its code instead of minting a second one — a new login invalidates nothing, but
+// it hands the user a different code than the one already on their screen.
+function pendingLogin() {
+  if (!existsSync(PIDFILE)) return null;
+  let state;
+  try {
+    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!state.pid || !alive(state.pid)) return null;
+  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
+  if (!ev) return null;
+  // Don't hand back a code that's about to expire mid-typing.
+  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
+  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
+  return ev;
+}
+
+// Detach so the login keeps polling after this process exits. stdio goes to a
+// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
+function startLogin() {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(LOG, '');
+  const out = openSync(LOG, 'a');
+  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: AGENT_ENV,
+    shell: isWin,
+  });
+  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
+  child.unref();
+}
+
+async function waitForCode(timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const events = loginEvents();
+    const ev = events.find((e) => e.event === 'awaiting_user');
+    if (ev) return ev;
+    const bad = events.find((e) => e.event === 'login_failed');
+    if (bad) fail('login_failed', bad);
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
+  fail('login_failed', {
+    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
+  });
+}
+
+// The next move is the user's, so hand the code back and exit rather than holding
+// the caller open for a browser round-trip. `message` is the sentence to relay.
+function surrenderTo(ev) {
+  emit('awaiting_user', {
+    ...ev,
+    message:
+      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
+      `${ev.userCode}. Tell me once you're done and I'll continue.`,
+  });
+  process.exit(0);
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+checkCli();
+
+if (hasExistingSession()) {
+  emit('logged_in');
+  process.exit(0);
+}
+
+const pending = pendingLogin();
+if (pending) surrenderTo(pending);
+
+startLogin();
+surrenderTo(await waitForCode());