@wix/agent-skills 1.23.0 → 1.24.0

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

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

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

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

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

@@ -1,9 +1,17 @@
 # A migration preview: a site being moved to headless
 
 Read when setup reports `mode: "migrate"`, or when a folder holds a `wix.config.json` and
-`node <SKILL_ROOT>/install/context.mjs` prints `migration.active: true`. The brief usually arrives
-as a project to download from Wix (a zip with the config), the names of the apps the site already
-has, and a request not to probe, install or seed anything.
+`node <SKILL_ROOT>/install/context.mjs` prints `migration.active: true`. The brief is the prompt
+the Wix dashboard's Headless settings hand the owner after "Go Headless": download the project from
+`https://manage.wix.com/download-headless-business/<siteId>/download.zip`, the names of the apps
+the site already has, and the instruction not to probe, install or seed anything. The zip holds
+`wix.config.json` (the deploy site and its app) beside the CLI's blank Astro starter.
+
+**What `.env.local` says.** `wix env pull` copies the project's `prod` environment: the parent's
+`WIX_CLIENT_ID`, and the migration's own variables, `EDITOR_MIGRATION_STATUS` (`ACTIVE` while the
+migration is under way, `COMPLETED` once the parent serves this frontend), `EDITOR_MIGRATION_PARENT_SITE_ID`,
+`EDITOR_MIGRATION_CHILD_SITE_ID` and `EDITOR_MIGRATION_CHILD_APP_ID`. `context.mjs` reads the first
+two; the shape is `migration` whenever the status is active, whatever else the folder holds.
 
 **Two sites, one project.** `wix.config.json` names a site created only to host the deployment:
 `wix release` goes there and nowhere else. `.env.local` (what `wix env pull` writes; setup and
@@ -28,16 +36,19 @@ manages. So:
   `read-site.mjs` sizes the content as in `guides/existing-site.md`; when it says not to probe,
   design from the brief.
 
-**The run.** `setup.mjs --vertical <vertical> [--stack <stack>]` in the folder: it copies the
-vertical's composed template around the config (managed Astro), deploys the code, starts the
-install, writes the project's AGENTS.md with the migration recorded, and skips the seed. Then
+**The run.** `setup.mjs --vertical <vertical>[,<vertical>…] [--stack <stack>]` in the folder (every vertical the brief needs, in one call): it keeps the
+starter the download carries and deploys the vertical's code and dependencies into it (a bare config
+gets the composed template copied in around it), starts the install, writes the project's AGENTS.md
+with the migration recorded, and skips the seed. Then
 SKILL.md steps 4 and 5 as for any run. `attach.mjs` refuses a migration folder on purpose: the
 app, hosting and credentials came with the download; nothing is provisioned or re-pointed.
 
 **The close.** The release is a **preview** on the deploy site. Close with the preview URL (copied
 from the `wix release` output), the parent's dashboard link, and the two facts: the original site
 is unchanged, and completing the migration, which makes the parent serve this frontend and retires
-the deploy site, is the user's next step in the Wix CLI once they approve the preview. That
-command is not part of this skill; do not invent one, do not run `wix release` against the parent,
-and do not edit `wix.config.json`. On every stack the code already carries the parent's client id,
+the deploy site, is the user's next step once they approve the preview: the dashboard hands them
+a second prompt for it (`wix env pull`, `wix finalize-migration`, `wix build`, `wix release`, in
+that order). That step is not part of this skill and the command may not be in the installed CLI
+yet; do not invent one, do not run `wix release` against the parent, and do not edit
+`wix.config.json`. On every stack the code already carries the parent's client id,
 so completion needs no redeploy from here.

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

@@ -29,6 +29,9 @@ Installed at `.agents/skills/`. If missing, restore with:
   site holds for it, with the documentation URL of every call it made. A code change ends with a release; the live URL shows it, the dev server does not count.
   `node .agents/skills/{{SKILL}}/install/check.mjs` says whether the skill or its templates have a newer
   version and prints the update commands; an update touches the skill folder or `templates/`, never `src/`.
+  When Wix gets in the way of a change here (a confusing error, a doc gap, a workaround you had to
+  invent), offer to relay it to Wix per `.agents/skills/{{SKILL}}/guides/feedback.md`; send only after
+  an explicit yes.
 - `wix-docs` — how to discover the Wix APIs and their docs: search first, then read only the page
   you need. Every endpoint, body, field and enum you did not get from the deployed code or a recipe
   is confirmed there before you write it.

package/skills/{wix-headless-fast → wix-headless-kit}/install/attach.mjs

@@ -45,7 +45,7 @@ import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync }
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
-import { siteContext } from "./context.mjs";
+import { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -76,7 +76,10 @@ const subfolder = argv.includes("--subfolder");
 const cwd = process.cwd();
 const has = (p) => existsSync(join(cwd, p));
 const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wix.config.json"), "utf8")) : null;
-const hasProject = has("package.json") || has("index.html");
+// A frontend here: a package.json, an index.html at the root, or an index.html in the folder the
+// config's site.outputDirectory names (a static site laid out for release) — install/context.mjs.
+const fp = frontendPresent(cwd);
+const hasProject = fp.packageJson || fp.rootIndex || fp.outputIndex;
 // A migration preview (wix.config.json names a deploy-only site, .env.local names the site being
 // migrated) is already provisioned: its app, hosting and credentials came with the folder. Nothing
 // here applies — setup.mjs takes it (SKILL.md step 3).

package/skills/{wix-headless-fast → wix-headless-kit}/install/check.mjs

@@ -24,7 +24,7 @@ const { repo } = installSource();
 const out = { skill: {}, templates: {}, update: {} };
 
 // ---- the repository: one clone of its history without file contents (small), read for both layers
-const tmp = mkdtempSync(join(tmpdir(), "wix-headless-fast-check-"));
+const tmp = mkdtempSync(join(tmpdir(), "wix-headless-kit-check-"));
 const clone = git(["clone", "--quiet", "--filter=blob:none", "--no-checkout", "--single-branch", repo, tmp]);
 if (clone.status !== 0) {
   rmSync(tmp, { recursive: true, force: true });

package/skills/wix-headless-kit/install/context.mjs

@@ -0,0 +1,169 @@
+// The site context of a project folder — the one place that says which site a call targets.
+//
+//   node <SKILL_ROOT>/install/context.mjs [--refresh] [--no-pull]     (prints one JSON object)
+//
+// Two identities live in a Wix project and are the same site almost always:
+//   deploy  — `wix.config.json` (`siteId`, `appId`): where `wix release` uploads. The CLI's business.
+//   content — `.env.local` (`WIX_CLIENT_ID`, what `wix env pull` writes): the app the SDK client
+//             runs as, on every stack (the Astro integration reads WIX_CLIENT_ID from the env and
+//             never the config; the other stacks get it copied into src/wix/config.ts by deploy.mjs).
+// They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
+// host the deployment, while `.env.local` carries the credentials of the site being migrated (the
+// parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
+// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
+// that does not exist yet; this module only reads the state.
+//
+// `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
+// identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
+// reported in `pullError` and the config's ids stand in, so a caller can still work offline.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// The variables the editor-to-headless migration writes into the child project's `prod`
+// environment (headless-bo, editorMigrations/environmentMetadata.ts), which `wix env pull` copies
+// into `.env.local` unchanged. The names are the platform's and are spelled once, here.
+export const ENV = {
+  clientId: "WIX_CLIENT_ID",
+  parentSiteId: "EDITOR_MIGRATION_PARENT_SITE_ID",
+  /** ACTIVE while the migration is under way; COMPLETED once the parent serves the child's frontend. */
+  status: "EDITOR_MIGRATION_STATUS",
+  childSiteId: "EDITOR_MIGRATION_CHILD_SITE_ID",
+  childAppId: "EDITOR_MIGRATION_CHILD_APP_ID",
+};
+
+/** KEY=value lines of a dotenv file, quotes stripped; null when the file is absent. */
+export function readEnvFile(file) {
+  if (!existsSync(file)) return null;
+  const out = {};
+  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function readWixConfig(cwd) {
+  const file = join(cwd, "wix.config.json");
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
+
+/**
+ * `wix env pull` into `cwd/.env.local`, in place. Every project shape gets the command since Wix CLI
+ * 1.1.253 (2026-09-29): before it, a config with `site.outputDirectory` (the static stack, a site
+ * published through the drop flow) landed in a limited command set without `env`, and this pulled
+ * through a temp copy of the config. Non-interactive; a failure comes back as `error`.
+ */
+export function pullEnv(cwd) {
+  const envFile = join(cwd, ".env.local");
+  const r = runPull(cwd);
+  if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
+  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
+}
+
+/**
+ * Whether a frontend exists in this folder: a `package.json` (a bundled project), an `index.html` at
+ * the root (plain pages), or an `index.html` inside the folder the config's `site.outputDirectory`
+ * names (a static site laid out for release, pages under site/). Nothing else counts — not this
+ * skill's code, not the skills folder, not AGENTS.md: those say who ran here, not what is here.
+ */
+export function frontendPresent(cwd = process.cwd()) {
+  const has = (p) => existsSync(join(cwd, p));
+  const outDir = (readWixConfig(cwd)?.site?.outputDirectory ?? "").replace(/^\.\//, "").replace(/\/$/, "");
+  return {
+    packageJson: has("package.json"),
+    rootIndex: has("index.html"),
+    outputIndex: !!outDir && outDir !== "." && has(join(outDir, "index.html")),
+    outputDirectory: outDir || null,
+  };
+}
+
+/**
+ * What the folder IS, from five file facts — the one classification every script and SKILL.md
+ * step 3 share: wix.config.json, its site.outputDirectory, the migration variables in .env.local,
+ * package.json, index.html. `migrationActive` comes from siteContext (it needs `.env.local`).
+ *
+ *   empty             nothing that reads as a project → setup CREATE: the run makes the site, seeds the plan
+ *   project           a frontend, no wix.config.json → setup ADOPT: `init` gives it a new, empty site, seeds the plan
+ *   config-only       a config, no frontend → attach.mjs on the config's site; nothing seeded
+ *   migration         a config whose .env.local declares an ACTIVE editor migration, with or without the blank
+ *                     Astro starter the download carries → setup MIGRATE; nothing seeded. Decided before the
+ *                     frontend test: the starter's package.json must not read as a project to iterate on
+ *   wix-project       a config AND a frontend (package.json, or index.html in the output folder) → iterate:
+ *                     never scaffold, init or reseed; deploy.mjs adds a solution, edits, release
+ *   published-static  a config, index.html at the ROOT, no package.json, no laid-out output folder (a site
+ *                     published through the drop flow and downloaded) → setup makes site/ the upload and
+ *                     deploys the REST layer; the config's site, no init, nothing seeded
+ */
+export function folderShape(cwd = process.cwd(), { migrationActive = false } = {}) {
+  const config = existsSync(join(cwd, "wix.config.json"));
+  const f = frontendPresent(cwd);
+  const next = {
+    empty: "setup.mjs --vertical <v> --business-name <brand> [--plan]: creates the site here and seeds the plan (CREATE)",
+    project: "setup.mjs --vertical <v> --stack <stack> [--plan]: init links the folder to a new, empty site, seeds the plan and deploys (ADOPT)",
+    "config-only": "attach.mjs: the site exists and has no frontend yet; read what it holds (the vertical's read-site.mjs) — nothing is seeded; the vertical's seed module with a plan only when the brief supplies or describes content",
+    migration: "setup.mjs (MIGRATE): the shipped code into the starter the download carries (or the composed template around a bare config); the site being migrated owns its content — guides/migration.md",
+    "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then ONE npm install; file edits for a change; release. Read the site (read-site.mjs) before any seed module runs",
+    "published-static": "setup.mjs --vertical <v>: the config's site, no init; site/ becomes the upload and the REST layer lands in site/js/wix/; move the pages, styles and assets into site/. Nothing is seeded: read the site, then run the vertical's seed module with a plan when the brief gives content; release keeps the URL",
+  };
+  let shape;
+  if (!config) shape = f.packageJson || f.rootIndex ? "project" : "empty";
+  else if (migrationActive) shape = "migration";
+  else if (f.packageJson || f.outputIndex) shape = "wix-project";
+  else if (f.rootIndex) shape = "published-static";
+  else shape = "config-only";
+  return { shape, next: next[shape], facts: { config, ...f } };
+}
+
+/**
+ * `{ folder: { shape, next, tells }, deploy: { siteId, appId }, content: { siteId, clientId },
+ *    migration: { active, parentSiteId }, env: { file, present, pulled }, pullError?, warnings: [] }`.
+ * `pull`: "auto" (default) pulls when `.env.local` is missing; true always; false never.
+ */
+export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
+  const config = readWixConfig(cwd) ?? {};
+  const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
+  const envFile = join(cwd, ".env.local");
+  let pulled = false, pullError;
+  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
+    const r = pullEnv(cwd);
+    if (r.ok) pulled = r.via;
+    else pullError = r.error;
+  }
+  const env = readEnvFile(envFile) ?? {};
+  const parentSiteId = env[ENV.parentSiteId] || null;
+  const status = env[ENV.status];
+  // ACTIVE (or a parent id with no status yet) is a migration under way; COMPLETED means the parent
+  // already serves this frontend and the project is an ordinary one again.
+  const active = !!parentSiteId && (status === undefined || status.trim().toUpperCase() === "ACTIVE");
+  const migration = { active, parentSiteId: active ? parentSiteId : null, ...(status ? { status: status.trim().toUpperCase() } : {}) };
+  const clientId = env[ENV.clientId] || deploy.appId;
+  const content = { siteId: active ? parentSiteId : deploy.siteId, clientId };
+  const warnings = [];
+  if (env[ENV.clientId] && deploy.appId && env[ENV.clientId] !== deploy.appId && !active && migration.status !== "COMPLETED") {
+    warnings.push(`.env.local ${ENV.clientId} differs from wix.config.json appId and no migration is declared — the SDK client runs as the env's app, the release goes to the config's site`);
+  }
+  if (active && migration.parentSiteId === deploy.siteId) {
+    warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
+  }
+  return { folder: folderShape(cwd, { migrationActive: active }), deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
+}
+
+// ---- CLI ----------------------------------------------------------------------------------------
+if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
+  const argv = process.argv.slice(2);
+  const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
+  console.log(JSON.stringify(siteContext({ pull }), null, 2));
+}

package/skills/{wix-headless-fast → wix-headless-kit}/install/deploy.mjs

@@ -111,6 +111,18 @@ const VERTICAL_DEPS = {
       "@wix/essentials": "^1.0.6",
     },
   },
+  rentals: {
+    // A rental is a Bookings service with rentals-specific values: the same SDK modules as bookings.
+    core: {
+      "@wix/bookings": "^1.0.1650",
+      "@wix/auto_sdk_ecom_cart-v-2": "^1.0.192",
+      "@wix/redirects": "^1.0.125",
+    },
+    astro: {
+      "@wix/seo": "^1.0.79",
+      "@wix/essentials": "^1.0.6",
+    },
+  },
   blog: {
     core: {
       "@wix/blog": "^1.0.645",
@@ -247,7 +259,7 @@ if (siteSearch) {
 }
 // The generated file is data only; the shipped core resolves defaults (types, routes, labels) from it.
 const siteSearchConfigSource = () =>
-  `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.siteSearch.\n` +
+  `// Generated by wix-headless-kit install/deploy.mjs from plan.capabilities.siteSearch.\n` +
   `// Edit the plan and redeploy. Defaults for anything omitted are in search-core.ts (resolveConfig).\n` +
   `export const siteSearchPlan = ${JSON.stringify(siteSearch, null, 2)};\n`;
 // ---- static stack: the REST layer, composed flat and stripped ------------------------------------
@@ -401,7 +413,7 @@ if (uploadPolicies.length) {
   // The generated file is data only. The shipped endpoint owns validation and elevation.
   writeFileSync(
     configFile,
-    `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.mediaUpload.\n` +
+    `// Generated by wix-headless-kit install/deploy.mjs from plan.capabilities.mediaUpload.\n` +
       `// Edit the plan and redeploy; do not add browser-controlled policy selection here.\n` +
       `export const mediaUploadPolicies = ${JSON.stringify(uploadPolicies, null, 2)} as const;\n`,
   );
@@ -506,8 +518,9 @@ if (!requested.length) {
 }
 
 // ---- client ids ---------------------------------------------------------------------------------
-// The shared data client is ambient on managed Astro. Members are different: their shipped
-// custom credential flow always needs an explicit public OAuth client, including on Astro.
+// The shared data client is ambient on managed Astro, and so is the members flow there (the
+// integration's built-in /api/auth routes). WIX_MEMBERS_CLIENT_ID is still filled for projects whose
+// members code predates the shared seam; the shipped code reads WIX_CLIENT_ID only.
 // --client-id, else the CONTENT app: .env.local's WIX_CLIENT_ID (what `wix env pull` writes — on a
 // migration preview the parent site's app, the one the Astro integration itself runs as), else the
 // config's appId. Never the config first: on a preview that is the deploy-only child app.