@wix/agent-skills 1.20.0 → 1.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-headless-fast/SKILL.md

@@ -5,24 +5,19 @@ description: "Build a Wix Headless site fast by wiring SHIPPED, verified @wix/sd
 
 # Wix Headless Fast
 
-Build a Wix Headless site by **deploying shipped code, not authoring it**. Where `wix-headless`
-hands the agent recipes to code from, this skill ships the integration itself — a typed data
-layer, hooks, components, pages, and a seed script that are already correct — and the agent's
-job narrows to brand, layout, copy, and wiring. The decisions live in the code; don't
+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
+seed script that are already correct. On a stack that runs it (Wix-managed Astro, any React
+project) the code is **deployed** and the agent's job narrows to brand, layout, copy, and wiring.
+On a stack that can't run it (a static site with no bundler, a server-rendered app in another
+language) the same code is the **reference**: its REST twin deploys for the browser side, and the
+rules it encodes are what the agent ports. Either way the decisions live in the code; don't
 re-litigate them.
 
-**Scope.** This is the bootstrap, tuned for Wix-managed Astro, and each vertical ships *one*
-shape of its solution. Deploy it as-is when the brief doesn't contradict it. When the brief
-asks for something that shape doesn't express — or once the site exists and the work turns to
-managing or extending it — that's `wix-docs` and `wix-manage`, not a workaround here.
-
-## Relationship to sibling skills
-
-| Skill                        | Use when                                                                                                               |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **wix-headless-fast** (this) | A supported vertical fits the request and the frontend is Astro or React — the fast path.                              |
-| `wix-headless`               | A vertical this skill doesn't ship yet, a non-React frontend, backend-only runs, or stripe/self-managed project types. |
-| `wix-vibe-headless`          | Client-only REST over a `WIX_CLIENT_ID` inside a vibe platform (Base44 etc.) — no SDK, no CLI.                         |
+**Scope.** Tuned for Wix-managed Astro, and each vertical ships *one* shape of its solution. Use
+it as-is when the brief doesn't contradict it. When the brief asks for something that shape
+doesn't express — or once the site exists and the work turns to managing or extending it — that's
+`wix-docs` and `wix-manage`, not a workaround here.
 
 ## The model
 
@@ -34,7 +29,7 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
     islands, with owner-editable item-page SEO pre-wired.
   - `seed/` — a build-time REST seed script (plain-data plan in, created content out) plus its
     `SEED.md` contract.
-  - `INSTRUCTIONS.md` — the vertical's playbook: file map, what you build, hard rules, verify.
+  - `INSTRUCTIONS.md` — the vertical's playbook: file map, what you build, hard rules.
 - **One auth seam.** All shipped code calls Wix through `src/wix/sdk.ts`: on Wix-managed Astro
   auth is ambient (no client, no id); on any other React setup the same file runs a manual
   visitor client off the public client id in `src/wix/config.ts`. The deploy step configures
@@ -49,6 +44,14 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
   INSTRUCTIONS names the surfaces you design and implement yourself on the shipped hooks,
   with a skeleton carrying each surface's contract (for storefront: the shop and PDP pages
   with their islands, and home).
+- **NEVER work from training data or memory about the Wix APIs.** Not a URL, a path, a version,
+  a header, a field name, a filter key, or a body. Every Wix call you make or write — in the
+  frontend, in a seed, in a build-time read of a site — comes from a source you have **open in
+  front of you**: this skill's shipped code, a `wix-manage` recipe, or a `wix-docs` page. No
+  source open, no call. A guessed call that returns 400 or an empty page is not a step toward
+  the answer; it is the failure this rule exists to prevent, and trying the next variant is
+  still guessing. The shipped code is tested against live sites; a body that looks similar is
+  the one that returns nothing, and the API rarely says why.
 - **Never mock, fail loudly, purchases via Wix.** Live data or an honest empty state; surfaced
   errors, not swallowed ones; checkout/purchase always through the Wix redirect session.
 - **Optional capabilities are deployed from the plan.** A vertical can opt into a shared
@@ -60,11 +63,28 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
 
 ## The run
 
-1. **Resolve the stack.** Default is **Wix-managed Astro** — take it unless the user names a
-   different React framework or the directory already holds a non-Astro React project. A
-   non-React frontend is out of scope → `wix-headless`.
-2. **Draft the seed plan** (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). Requires from here on: Node ≥ 20.11 and a logged-in Wix CLI
+1. **Resolve the stack.** Default is **Wix-managed Astro** — take it unless the user names
+   another framework or the directory already holds one. Then, by what the shipped code can run
+   there:
+   - **React** (Vite, Next, …) runs everything shipped — data layer, hooks, components:
+     `--stack react`. The agent's own files may be JS.
+   - **Another bundled JS framework** (Vue, Svelte, Solid, plain Vite): the data layer and the
+     framework-free stores run (`src/wix/` has no React in it), the React hooks and components
+     don't apply: `--stack lib`. The agent binds the stores and writes its framework's components
+     against the same contracts.
+   - **No bundler, or another language** — a static site (plain HTML/CSS/JS), a server-rendered
+     app (Flask, Laravel, Rails, …): **reference mode** (below). Nothing from `app/` deploys; the
+     REST layer deploys for the browser side, and the server side ports it for its reads.
+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 `references/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). Requires from here on: Node ≥ 20.11 and a logged-in Wix CLI
    (`npx @wix/cli@latest whoami`; login via the device-code flow — surface the URL+code, never
    read tokens into context).
 3. **Create runs (empty directory): run the fast path** — one deterministic call:
@@ -80,12 +100,11 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
    you / the enclosing repo, so it does **not** create the scaffold's usual git repo + initial
    commit (which would otherwise become a nested-repo gitlink if the project lands inside a repo).
 
-   Optional `--flatten`: by default the project is created in a **new subfolder** (named after the
-   business). Pass `--flatten` to create it **directly in the current directory** instead — a plain
-   move of the scaffold's files up into the CWD, done **before** the dependency install starts so
-   nothing is half-moved (and since git was skipped, there's no nested repo to reconcile). Use it
-   when bootstrapping into an existing repo that must stay a single flat tree; otherwise omit it
-   and keep the subfolder.
+   The project is created **in the current directory** — the folder the entry had you work from,
+   which already holds the installed skills — so the project is self-contained and a later session
+   opened in it finds everything. It refuses if the folder already holds a file the scaffold would
+   write. `--subfolder` creates it in a new folder named after the business instead, for a current
+   folder that must stay as it is; the skills then sit one level above the project.
 
    It emits one JSON event per line and returns in **~35s**: **scaffolds** the project,
    **deploys** the shipped code (patching `package.json` with every dependency the code
@@ -96,6 +115,59 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
    and both markers. Relay notable events. On an `error` event, recover just that step via the
    manual path below, then continue.
 
+   **Existing-site runs (the brief names a Wix site by its id — a new frontend for a site that
+   already has its content): read the site, then run attach.** First, one call tells you what
+   the site is — its name, currency, and the Wix apps installed on it:
+
+   ```bash
+   curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+     -H "Authorization: $(npx -y @wix/cli@latest token)" -H 'Content-Type: application/json' \
+     -d '{"siteId": "<siteId>"}'
+   ```
+
+   The installed apps name the verticals (Wix Stores → storefront, Wix Bookings → bookings, and
+   so on per the Verticals table); the brief picks among them. Then one deterministic call, same
+   shape as the fast path:
+
+   ```bash
+   node <SKILL_ROOT>/install/attach.mjs --site <siteId> --business-name "<site name>" --vertical <vertical>[,<vertical>]
+   ```
+
+   `init`/`wix create` always create a site, so they are not used here. attach does what they do
+   after creating one — the site's OAuth app, Wix hosting, `wix.config.json` — against the site
+   given, scaffolds the CLI's Astro template, deploys the shipped code, and starts the install
+   detached. No seed runs and nothing on the site changes: the content is the site's own, read
+   live through the deployed data layer. When the site already has a headless frontend,
+   `attached` says so (`hosting: "reused"`) with its URL — `wix release` from this project
+   replaces that frontend; say so when you close.
+
+   **Get the measure of the site before you design.** Enough to know what you are building
+   for: what the chosen verticals will render, roughly how much of it, and what it is like — a
+   bakery with six products in three categories designs differently from six hundred. Go
+   deeper only where the brief points (a flash sale on cakes: is there a Cakes category, do the
+   cakes carry a sale price). Everything else the pages read live through the deployed data
+   layer; you are sizing the content, not collecting it. These are build-time reads with the
+   **site's** token, `npx -y @wix/cli@latest token --site <siteId>`, sent raw as the
+   `Authorization` header (the account token from the call above does not scope to a site).
+   **The rule above applies in full: not one of these calls comes from memory.** Open the
+   source first, then call. Three sources, in this order:
+   - **The vertical's shipped `rest/` module**, at
+     `.agents/skills/wix-headless-fast/references/<vertical>/rest/` — the same reads the pages
+     make, written as literal `fetch` calls: URL, body, `fields`, filter keys. It is not in
+     `src/` (the Astro stack deploys the SDK layer, which hides the body behind a method), so
+     read it from the skill.
+   - **`wix-manage`**, at `.agents/skills/wix-manage/` — REST recipes for managing a site's
+     business solutions: exact endpoint, method and payload per operation, curl included. Its
+     SKILL.md is the index, by solution; open the recipe for the vertical's solution.
+   - **`wix-docs`**, at `.agents/skills/wix-docs/` — the Wix API reference, reached by
+     **search, not by browsing files**: the skill folder holds the how-to, not the pages. Open
+     its SKILL.md; it gives one `curl` to semantic search (`POST
+     /mcp-docs-search/v1/docs/search/markdown`, natural-language `search_term`) that returns
+     condensed method docs — endpoint, request example, response shape — and the rule that any
+     `dev.wix.com/docs/…` URL plus `.md` is the full page. Progressive: search first, read the
+     full page only when the hit lacks what you need.
+   If the source you opened does not have the call, go to the next one; do not try a variant.
+
    **Connect/iterate runs (a project already on disk): never scaffold — use the manual path:**
    `CI=1 npm create @wix/new@latest init` in place if there is no `wix.config.json` yet; then
    `node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack astro|react --plan plan.json` from the project root
@@ -122,7 +194,12 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
 5. **When both background jobs have completed** — the install's marker
    (`node_modules/.package-lock.json`) and the seed's (`.seed-exit`) both exist — **verify the
    seed succeeded** (`.seed-exit` contains `0`; `seed-result.json` has the created counts for
-   your summary — if non-zero, read `seed.log` and re-run the seed module manually). Then
+   your summary — if non-zero, read `seed.log` and re-run the seed module manually). Those two
+   seed files exist **only when fast-path 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
+   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):
    `npx @wix/cli@latest build` then `npx @wix/cli@latest release` (if the install failed, run
    it once more and then build). Don't build+release mid-flow; backend content is fetched at
@@ -132,8 +209,91 @@ managing or extending it — that's `wix-docs` and `wix-manage`, not a workaroun
    `wix release` output — never retype it from memory** (a mistyped subdomain hands the user
    a 404).
 
-Don't smoke-test with a dev server unless the user explicitly asks to verify — correctness
-comes from the shipped code, and real errors surface at build/release.
+## Reference mode — a static site, or a server-rendered app in another language
+
+The data layer ships a second time as a **REST layer**: `references/shared/rest/` (the auth seam
+`client.ts`, `media.ts`, `config.ts`) and `references/<vertical>/rest/` (the same exports as the
+vertical's `app/wix/<vertical>/` data layer, over `fetch`), typed against the same `types.ts` and
+importing the same `*-core.ts` rule files as the SDK layer — one implementation of the rules, two
+transports. The vertical's `INSTRUCTIONS.md` names its modules and what each surface does with
+them; this section is the mechanics, the same for every vertical.
+
+- **Static site (no bundler).** `npm create @wix/new@latest init` in the project folder (site,
+  OAuth app, `wix.config.json`). The site lives in a **subfolder** — `site/` — holding only the
+  pages, styles, and `js/`; set `site.outputDirectory` in the config to `"./site"`. `wix release`
+  uploads that directory whole, so the project root (config, `plan.json`, seed output, anything
+  else) must not be it. Then `node <SKILL_ROOT>/install/deploy.mjs <vertical> --stack static --out
+  site` composes the REST layer and the vertical's framework-free stores flat into `site/js/wix/`
+  and strips them to browser ESM (comments kept, the `.ts` kept beside the `.js` to read). Pages
+  import the vertical's modules from `./js/wix/` in a `<script type="module">`: the stores hold
+  the state machines (subscribe, render from `getState()`, call actions), the page holds the
+  rendering. The visitor token lives in `localStorage` and is the
+  visitor's identity across Wix — never mint one per page. A route is a page plus a query-string
+  slug (`item.html?slug=…`). Wix static hosting serves files, not directories: `/shop` does not
+  resolve to `shop/index.html`, and there is no routes configuration — name the file and link
+  to it. Seed per the vertical's `SEED.md` (Node + the CLI token, no project dependencies).
+  Release with `npx @wix/cli@latest release` — no build. Item-page tags come from the entity's
+  `seoData`, set after the fetch (`document.title`, the meta description).
+- **Server-rendered, another language (Flask, Laravel, Rails, …).** The same shape as managed
+  Astro — pages rendered on the server, the interactive surfaces in the browser — with hosting and
+  SEO plumbing theirs. `init` still runs in the project folder; run `deploy.mjs <vertical> --stack
+  static` there too: it only needs `wix.config.json` and writes `js/wix/`. Split by where the call
+  runs:
+  - **Reads render on the server.** Port the vertical's `rest/` read module and its `*-core.ts` to
+    the server language: each function is one HTTP call with a literal URL and JSON body, and the
+    core carries the rules. That code is tested and proven against live sites — carry its bodies
+    over as they are, `fields` arrays and filter keys included (they are not guessable, and a
+    near-miss returns empty or unformatted data with no error), and render what Wix returns
+    (`formattedAmount`, never a number you format yourself). The shipped JS runs: when in doubt,
+    run the module with Node against the same site and compare one entity with your port. Public
+    reads need no visitor identity — one anonymous visitor token per server process, refreshed per
+    `client.ts`, is enough for them.
+  - **Visitor-specific state runs in the browser.** Whatever the vertical does on the visitor's
+    behalf (a store's cart and checkout, a booking, an RSVP, a form submit) loads the vertical's
+    `js/wix/` module in the templates and talks to Wix from the page, exactly as a static site
+    does: the browser owns the visitor token in `localStorage`, so the server handles no
+    per-visitor tokens. If that state must run server-side anyway, `client.ts`'s header applies:
+    one token set per visitor in the visitor's session, never one process-wide token (that is one
+    identity shared by everyone).
+  - **Pre-rendered → Wix-hosted.** If the project builds to static HTML (Frozen-Flask, Pelican,
+    Hugo, Eleventy, any static-site generator), Wix can host the output: run `deploy.mjs
+    <vertical> --stack static --out <build dir>` so `js/wix/` lands inside the build output (or
+    copy it there after each build), make the generator emit a page for **every** entity slug the
+    vertical's list read returns (walk it by cursor, never only the first page), point
+    `site.outputDirectory` at the build folder, `wix release`. The build's own reads use one
+    anonymous visitor token for the duration of the build. What Wix hosts is exactly the contents
+    of that folder after your last build, served as files: every asset a page references must be
+    in there and current — if the pipeline has more than one build step (templates, then a CSS or
+    asset bundle), they all run, in order, on every rebuild, or the release carries a stale piece.
+    `/shop` does not resolve to `shop/index.html`; name the file and link to it. Generated pages
+    sit at different depths, so reference `js/wix/` through one base path (a template variable,
+    or root-relative `/js/wix/…`), never `./js/wix/` — a relative path breaks one level down. **The generated page
+    is the first paint, not the whole surface**: the vertical's interactive behaviour (a store's
+    sort, filters, and cart; a blog's search; a booking flow) still runs client-side on top of it
+    from the same `js/wix/` modules, so the vertical's surface contracts in `INSTRUCTIONS.md`
+    apply unchanged. Close with the rebuild + release command and one line for the owner: content
+    edits made in the dashboard reach the site when that command runs; the browser-side flows are
+    live regardless. A running server (live reads on every request) stays theirs to host.
+  Then read the vertical's `INSTRUCTIONS.md` for the surfaces and hard rules, and the shared
+  `DESIGN.md`/`CONTENT.md`. **Before writing any surface, read the vertical's shipped hooks and
+  components** — its `INSTRUCTIONS.md` lists which files and what to take from each. They don't
+  deploy on this stack, and they are working, tested code for exactly the behaviour you are about
+  to write in your own; rewriting them from prose is where the bugs come from (the runs that
+  skipped them shipped a broken quick-add, the run that read them didn't). Both were written for
+  the stacks that receive the code, so they speak that stack's dialect: the Tailwind classes in the
+  skeletons and the components are one spelling of layout and behaviour rules that hold everywhere
+  (a bounded image band on phones, name and price on separate lines, the buy control pinned to the
+  tile's bottom, an overlay that locks scroll and returns focus). Take the rules; write them in the
+  CSS your stack uses, on a token set you define — nothing here asks you to add Tailwind. Close with run (or
+  rebuild) instructions, the live URL when Wix hosts the output, the dashboard link, and — when
+  hosting is theirs — the allowed-domain step (add the public https origin to the OAuth app
+  before a Wix-hosted flow such as checkout can return).
+- Both: the calls in `rest/` are the ones a **visitor token** may make from a page — public reads
+  and the visitor's own actions. Anything elevated (writes to content, other people's data) runs
+  server-side per `references/shared/CUSTOM_OPERATIONS.md`; the seed's CLI token never belongs in
+  a page. A static site has no SSR; neither case has owner-editable item-page SEO through
+  `@wix/seo` (tags come from the entity's `seoData`) — say so in the closing message; managed
+  Astro stays the recommendation for a public site.
 
 ## Verticals
 
@@ -164,10 +324,11 @@ New verticals follow the same layout — the deploy script discovers them automa
 
 ```
 references/<vertical>/
-  INSTRUCTIONS.md      # playbook: file map, wiring per stack, what you build, hard rules, verify
+  INSTRUCTIONS.md      # playbook: file map, wiring per stack, what you build, hard rules
   app/                 # framework-agnostic core — disjoint paths so verticals never collide:
     wix/<vertical>/    #   types.ts (DTOs) + data layer (calls via ../sdk, images via ../media)
-    hooks/<vertical>/  #   React hooks (SSR-friendly: accept initial data)
+                       #   + *-store.ts: the state machines, framework-free (ship on every stack)
+    hooks/<vertical>/  #   React hooks — thin bindings of the stores (SSR-friendly: accept initial data)
     components/<vertical>/  # routing-free components (plain <a> default + LinkComponent prop)
     styles/global.css  # Tailwind v4 + the @theme design tokens (shared token family)
   app-astro/           # Astro overlay importing ONLY from the core:
@@ -176,9 +337,14 @@ references/<vertical>/
                        #   (storefront ships no pages — its INSTRUCTIONS carries their skeletons)
     layouts/…          #   (reuse SiteLayout when it fits)
   seed/                # seed-<vertical>.mjs (REST, mints its own CLI token) + SEED.md
+  rest/                # the REST twin of app/wix/<vertical>/: same exports over fetch, importing
+                       #   the same *-core.ts (rules + DTO mappers, type-only imports) and types.ts;
+                       #   flat ./x.js imports — deploy --stack static composes and strips it
 ```
 
-Core rules the structure encodes: raw API entities never leave the data layer (DTOs only);
+Core rules the structure encodes: a rule or mapper lives once, in `app/wix/<vertical>/*-core.ts`,
+imported by both transports (a call added to `app/` gets its `rest/` twin in the same PR; `tsc`
+over both is the parity check); raw API entities never leave the data layer (DTOs only);
 client-shared state uses a module-scope store (never React context — it can't span Astro
 islands); every image URL is resolved through `src/wix/media.ts`; every money value is a
 formatted string by the time a component sees it.

package/skills/wix-headless-fast/entry/skill.md

@@ -28,18 +28,26 @@ This entry gets a cold environment to the point where the real skill can run, th
 2. **Hand off (agentic).** Install the skills, then open `wix-headless-fast/SKILL.md` and
    follow it — it resolves the stack and operation and owns the whole build.
 
-Three starting points come through here, all handled the same way — run the bootstrap, then
+Four starting points come through here, all handled the same way — run the bootstrap, then
 hand off:
 
 - **new** — a prompt with no project (empty CWD)
 - **connect** — an existing frontend/design not yet on Wix (a project on disk without
   `wix.config.json`, or a brought-in zip/URL)
 - **iterate** — a project already connected to Wix (`.wix/` or `wix.config.json` present)
+- **existing site** — the prompt names a Wix site that already exists (by its site id) and asks
+  for a new frontend for it; the site keeps its content, the frontend is built here
 
 The bootstrap only verifies the CLI and logs you in, so it's fine to run in every case (an
 existing session just reports `logged_in`).
 
-## Phase 0 — Node (the one manual prerequisite)
+## Phase 0 — The project's folder, and Node
+
+**Work from the folder that will hold the project.** For a **new** build: an empty folder is the
+project; if the current folder is not empty, make one named for the business and `cd` into it.
+For **connect**, **iterate** and **existing site**: you are already in it. Everything below — the
+bootstrap, the skills, the scaffold — lands in this folder, so a later session opened in the project
+finds all of it.
 
 The Wix CLI requires **Node ≥ 20.11**. Check `node -v`; if it errors or prints a lower
 version, install or upgrade Node first — do **not** work around it:

package/skills/wix-headless-fast/install/attach.mjs

@@ -0,0 +1,253 @@
+// Attach a NEW headless frontend to an EXISTING Wix site — the fast path for a site that already
+// exists (named in the prompt by its id). `init`/`wix create` cannot do this: they always create
+// a site. This script does what they do AFTER creating one — OAuth app, managed hosting, env
+// vars, `wix.config.json` — against the site id given, then scaffolds and deploys like
+// fast-path.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+//
+//   node <SKILL_ROOT>/install/attach.mjs --site <metaSiteId> --business-name "<Brand>" \
+//        --vertical <a>[,<b>…] [--stack astro|react|static] [--subfolder [--folder-name <name>]]
+//
+// --business-name  the site's name (names the folder, the hosting slug and the app project).
+// --vertical       which shipped code deploys (no seed runs — the site owns its content). Both are
+//                  the caller's decision, read off the site before calling this (SKILL.md step 3).
+// --stack       astro (default): scaffolds the CLI's blank Astro template with the hosting adapter,
+//               ready for `wix build` / `wix release`. react|static: writes wix.config.json into the
+//               folder and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md.
+// The project is created in the CURRENT DIRECTORY — the folder that already holds the installed
+// skills — so it is self-contained. `--subfolder` (opt-in) creates it in a new folder named after
+// the business instead.
+//
+// Emits ONE JSON event per line (attached, scaffolded, deployed, install_started,
+// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@latest whoami`)
+// whose account owns or co-manages the site.
+import { spawn, spawnSync, execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const MANAGE = "https://manage.wix.com";
+const HEADLESS_PROJECT_TYPE_ID = "eb363dea-85a0-4159-9b05-949542be5079";
+const TEMPLATES_REPO = "https://github.com/wix/headless-templates.git";
+const TEMPLATE_PATH = "astro/blank";
+
+const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
+const fail = (step, detail) => {
+  emit("error", { step, detail: String(detail).slice(0, 600) });
+  process.exit(1);
+};
+
+// ---- args ---------------------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
+};
+const siteId = flag("site");
+const stack = flag("stack") ?? "astro";
+const subfolder = argv.includes("--subfolder");
+const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
+  .map((d) => d.name);
+const verticals = argv
+  .flatMap((a, i) => (a === "--vertical" && argv[i + 1] ? argv[i + 1].split(",") : []))
+  .map((v) => v.trim())
+  .filter(Boolean);
+const businessName = flag("business-name");
+if (!siteId || !/^[0-9a-f-]{36}$/i.test(siteId) || !businessName || !verticals.length) {
+  fail("args", `usage: attach.mjs --site <metaSiteId> --business-name "<Brand>" --vertical <${knownVerticals.join("|")}>[,…] [--stack astro|react|static]`);
+}
+for (const v of verticals) if (!knownVerticals.includes(v)) fail("args", `unknown vertical "${v}" — shipped verticals: ${knownVerticals.join(", ")}`);
+if (!["astro", "react", "static"].includes(stack)) fail("args", `unknown stack "${stack}" — astro, react or static`);
+if (existsSync(join(process.cwd(), "wix.config.json"))) {
+  fail("args", "the current directory is already a Wix project (wix.config.json) — attach creates a new frontend; run deploy.mjs here instead");
+}
+
+// ---- http ---------------------------------------------------------------------------------------
+const cliToken = (site) => {
+  const r = spawnSync("npx", ["-y", "@wix/cli@latest", "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
+  const t = (r.stdout || "").trim();
+  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || "no token — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-400));
+  return t;
+};
+async function call(base, path, { method = "POST", token, site, body, query } = {}) {
+  const url = new URL(base + path);
+  for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, String(v));
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: token,
+      "Content-Type": "application/json",
+      "X-XSRF-TOKEN": "nocheck",
+      Cookie: "XSRF-TOKEN=nocheck",
+      "User-Agent": "wix-cli",
+      ...(site ? { "wix-site-id": site } : {}),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${method} ${url.pathname} ${res.status}: ${text.slice(0, 300)}`);
+  try { return JSON.parse(text); } catch { return {}; }
+}
+
+const folderName = flag("folder-name") ?? (businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "site");
+const projectDir = subfolder ? resolve(process.cwd(), folderName) : process.cwd();
+if (subfolder && existsSync(join(projectDir, "wix.config.json"))) fail("args", `${folderName}/ is already a Wix project — pick --folder-name, or run deploy.mjs there`);
+
+// ---- 1 · attach: OAuth app + hosting + env, on the manage host with a site token -----------------
+// The same calls `init` makes after it has created a site, in the same order.
+const siteToken = cliToken(siteId);
+const opts = { token: siteToken, site: siteId };
+let appId, appProject, instanceId, secrets, hosting = "created";
+try {
+  const comp = await call(MANAGE, "/_api/companion-apps/v1/companion-apps/get-or-create", { ...opts, body: {} });
+  appId = comp.companionApp?.id;
+  if (!appId) throw new Error("get-or-create returned no companion app id");
+  const slug = folderName;
+  try { appProject = (await call(MANAGE, `/_api/wix-code-app-projects/v1/app-projects/${appId}`, { ...opts, method: "GET" })).appProject; } catch { appProject = null; }
+  if (appProject) {
+    hosting = "reused";
+  } else {
+    try { await call(MANAGE, `/apps-service/v1/apps/${appId}/set-namespace`, { ...opts, method: "PATCH", body: { appId, appName: businessName, namespace: slug } }); }
+    catch (e) { emit("note", { step: "set-namespace", detail: String(e.message).slice(0, 200) }); }
+  }
+  try {
+    const inst = await call(MANAGE, "/apps-installer-service/v1/app-instance/install", { ...opts, body: { tenant: { id: siteId, tenantType: "SITE" }, appInstance: { appDefId: appId, version: "latest" } } });
+    instanceId = inst.appInstance?.id;
+  } catch (e) { emit("note", { step: "install", detail: String(e.message).slice(0, 200) }); }
+  secrets = (await call(MANAGE, `/apps-service/v1/apps/${appId}`, { ...opts, method: "GET", query: { withSecrets: true } })).app?.appSecrets;
+  if (!secrets?.appSecret) throw new Error("app secrets unavailable for this app");
+  if (!appProject) {
+    appProject = (await call(MANAGE, "/_api/wix-code-app-projects/v1/app-projects", { ...opts, body: { appProject: { id: appId, displayName: businessName.slice(0, 50), slug, appProjectTypeId: HEADLESS_PROJECT_TYPE_ID } } })).appProject;
+  }
+  if (!appProject?.baseUrl) throw new Error("app project has no baseUrl");
+  const prod = String(appProject.baseUrl).replace(/\/$/, "");
+  const host = new URL(appProject.baseUrl).hostname;
+  const local = "http://localhost:4321";
+  await call(MANAGE, `/oauth-app-service/v1/oauth-apps/${appId}`, { ...opts, method: "PATCH", body: {
+    oAuthApp: {
+      id: appId,
+      allowedDomains: [local, `https://(.*)-${host}`, prod],
+      allowedRedirectUris: [`${local}/api/auth/callback`, `${local}/api/auth/logout-callback`, `https://*-${host}/api/auth/callback`, `https://*-${host}/api/auth/logout-callback`, `${prod}/api/auth/callback`, `${prod}/api/auth/logout-callback`],
+      redirectUrlWixPages: prod,
+      origin: "other",
+    },
+    mask: { paths: ["allowedDomains", "allowedRedirectUris", "redirectUrlWixPages", "origin"] },
+  } });
+  if (!instanceId) {
+    // reused app: the instance id is on the existing env, keep it
+    try {
+      const env = await call(MANAGE, `/_api/wix-code-app-environments/v2/app-projects/${appProject.id}/app-environment-variables`, { ...opts, method: "GET", query: { environment: "system_global" } });
+      instanceId = (env.appEnvironmentVariables ?? []).find((v) => v.key === "WIX_CLIENT_INSTANCE_ID")?.value ?? null;
+    } catch { /* fall through */ }
+  }
+  const variables = { WIX_CLIENT_ID: appId, WIX_CLIENT_SECRET: secrets.appSecret, WIX_CLIENT_PUBLIC_KEY: secrets.webhookPublicKey, ...(instanceId ? { WIX_CLIENT_INSTANCE_ID: instanceId } : {}) };
+  await call(MANAGE, `/_api/wix-code-app-environments/v2/bulk/app-projects/${appProject.id}/app-environment-variables/upsert`, { ...opts, body: {
+    appProjectId: appProject.id, environment: "system_global", mutability: "STATIC", returnEntity: true, returnAllEnvironment: true, variables,
+  } });
+} catch (e) {
+  fail("attach", e?.message || e);
+}
+const baseUrl = String(appProject.baseUrl).replace(/\/$/, "");
+emit("attached", { siteId, appId, baseUrl, hosting, note: hosting === "reused" ? "this site already has a headless frontend at baseUrl; `wix release` from this project replaces it" : undefined });
+
+// ---- 2 · scaffold -------------------------------------------------------------------------------
+mkdirSync(projectDir, { recursive: true });
+if (stack === "astro") {
+  // The CLI's own blank template (what `wix create` copies), then what its extender adds: the
+  // hosting adapter, React islands, the `wix` scripts. Pinned like a freshly created project.
+  const tmp = mkdtempSync(join(tmpdir(), "wix-template-"));
+  const clone = spawnSync("git", ["clone", "--quiet", "--depth", "1", "--filter=blob:none", "--sparse", TEMPLATES_REPO, tmp], { encoding: "utf8", timeout: 120_000 });
+  if (clone.status !== 0) fail("scaffold", clone.stderr || "git clone of the template repo failed");
+  const sparse = spawnSync("git", ["-C", tmp, "sparse-checkout", "set", TEMPLATE_PATH], { encoding: "utf8", timeout: 60_000 });
+  if (sparse.status !== 0 || !existsSync(join(tmp, TEMPLATE_PATH, "package.json"))) fail("scaffold", sparse.stderr || `template ${TEMPLATE_PATH} not found in ${TEMPLATES_REPO}`);
+  cpSync(join(tmp, TEMPLATE_PATH), projectDir, { recursive: true, force: false, errorOnExist: false });
+  rmSync(tmp, { recursive: true, force: true });
+  const pkgPath = join(projectDir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.name = folderName;
+  pkg.scripts = { astro: "astro", dev: "wix dev", build: "wix build", wix: "wix", preview: "wix preview", release: "wix release", generate: "wix generate", env: "wix env", skills: "wix skills" };
+  pkg.devDependencies = {
+    ...(pkg.devDependencies ?? {}),
+    "@astrojs/react": "^4.3.0",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@wix/cli": "^1.1.92",
+    "@wix/astro-wix-hosting-adapter": "^2.0.0",
+    react: "18.3.1",
+    "react-dom": "18.3.1",
+  };
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  writeFileSync(join(projectDir, "astro.config.mjs"), `// @ts-check
+import { defineConfig } from "astro/config";
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+  image: { domains: ["static.wixstatic.com"] },
+  output: "server",
+});
+`);
+  const gi = join(projectDir, ".gitignore");
+  const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/\.env/.test(cur)) writeFileSync(gi, cur + "\n# local env (pulled from Wix)\n.env.local\n.env\n");
+}
+writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify({ appId, siteId }, null, 2) + "\n");
+// The env the CLI's build reads. Same content `wix env pull` writes; written here so the build
+// needs no extra call.
+const quote = (v) => `"${String(v ?? "").replace(/"/g, '\\"')}"`;
+writeFileSync(join(projectDir, ".env.local"), [
+  `WIX_CLOUD_PROVIDER=${quote("wix")}`,
+  `WIX_CLIENT_ID=${quote(appId)}`,
+  ...(instanceId ? [`WIX_CLIENT_INSTANCE_ID=${quote(instanceId)}`] : []),
+  `WIX_CLIENT_PUBLIC_KEY=${quote(secrets.webhookPublicKey)}`,
+  `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
+  "",
+].join("\n"));
+emit("scaffolded", { folder: folderName, stack, template: stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+
+if (stack !== "astro") {
+  emit("ready", { projectDir, siteId, appId, baseUrl, hosting, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
+    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack} (the client id is read from wix.config.json); no seed — the site owns its content` });
+  process.exit(0);
+}
+
+// ---- 3 · deploy shipped code + deps + lockfile ---------------------------------------------------
+let deployResult = {};
+{
+  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
+  if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
+  try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going */ }
+  if (deployResult.error) fail("deploy", deployResult.error);
+  emit("deployed", deployResult);
+}
+
+// ---- 4 · dependency install, detached -----------------------------------------------------------
+const installLog = join(projectDir, "npm-install.log");
+const logFd = openSync(installLog, "a");
+const install = spawn("sh", ["-c", "npm ci --ignore-scripts || npm install --ignore-scripts"], { cwd: projectDir, detached: true, stdio: ["ignore", logFd, logFd] });
+install.unref();
+emit("install_started", { log: installLog, doneMarker: "node_modules/.package-lock.json" });
+
+// ---- done ----------------------------------------------------------------------------------------
+emit("ready_for_brand_layer", {
+  projectDir,
+  siteId,
+  appId,
+  baseUrl,
+  hosting,
+  verticals,
+  dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
+  productsUrl: deployResult.productsUrl,
+  categoriesUrl: deployResult.categoriesUrl,
+  install: { log: installLog, doneMarker: "node_modules/.package-lock.json" },
+  seed: null,
+  next: "the site's content is live already — nothing to seed; read what it holds through the deployed data layer, theme SiteLayout + write the pages; wait for the install marker, build, release",
+});