@wix/agent-skills 1.20.0 → 1.21.0

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,21 @@ 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 the official Wix skills
+  installed here, the code they deployed first, or, when they do not cover the call, from the
+  official Wix documentation through `wix-docs`. Read it there first, then write the call.
+  **The test, before every request:** the exact path and body appear in the output of a file
+  read or a docs search you ran in this session, and you copy them from that output. Anything
+  else is memory: a file whose output was cut short before the call, a source you remember
+  reading earlier, a call built by changing part of one you did find. A guessed call that
+  returns 400 or nothing is not a step toward the
+  answer; it is the failure this rule exists to prevent, trying the next variant is still
+  guessing, and an empty or error reply to a call that failed the test tells you about the
+  call, never about the site. Keep errors visible while a call is unconfirmed: no `2>/dev/null`,
+  no `| echo`. 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,32 +70,104 @@ 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; the shipped files are TypeScript and
+     build untouched inside a JS project — never strip them by hand; if the brief wants no
+     TypeScript anywhere, say the shipped code cannot meet that and ask before going on.
+     A named framework is scaffolded with its own command
+     first (`npm create vite@latest`, …), then step 3 runs in that folder.
+   - **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.
+
+   **What Wix hosting takes, and what each stack needs to be released there.** `wix release`
+   uploads the folder named in `wix.config.json` (`site.outputDirectory`) and serves it as
+   files — no SPA fallback, no directory index, no rewrites: `/` and real files resolve, a clean
+   client-side route answers 404 when loaded directly or shared. Server code runs only as a
+   Cloudflare Workers build, declared as `outputDirectory: { client, server }`.
+   - **Managed Astro** is the stack the Wix CLI scaffolds: the Wix Astro integration
+     (`@wix/astro`, ambient auth), the hosting adapter (`@wix/astro-wix-hosting-adapter`, the
+     Workers build), `@astrojs/react` with React 18 for the shipped components, and in
+     `astro.config.mjs` `integrations: [wix(), react()]`, `adapter: wixHostingAdapter()`,
+     `output: "server"`, `security: { checkOrigin: false }`, `image.domains` with
+     `static.wixstatic.com`. An Astro project made without the CLI has none of that; add it
+     before deploying, and the site serves every route. The integration supports **Astro 5**: a
+     project on another major is pinned to 5 first, or connected as a React host.
+   - **React and other bundlers** release their own build as files. So routes are hash routes,
+     or one emitted HTML file per route linked by its file name — decided before the first route
+     is written; any URL handed to Wix as a return target must be one the host serves. Verify by
+     loading a deep URL directly, not by navigating from `/`.
+   - **A framework whose build is a server** (Next, Nuxt, Remix, SvelteKit, …) releases only as a
+     static export (files, the rule above applies), or as a Workers build through
+     `outputDirectory: { client, server }`; otherwise it is self-hosted, with its domain added to
+     the OAuth app's allowed domains before checkout can return to it.
+   - **Static** (no build): `outputDirectory` points at the folder the pages live in; a route is a
+     page plus a query-string slug (reference mode, below).
+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:
+3. **Set up the project, in its folder** — one deterministic call, the same for an empty folder
+   and for a project already on disk; **the folder decides** what it does:
 
    ```bash
-   node <SKILL_ROOT>/install/fast-path.mjs --business-name "<Brand>" --plan plan.json --vertical <vertical>
+   node <SKILL_ROOT>/install/setup.mjs --vertical <vertical> [--plan plan.json] [--business-name "<Brand>"]
    ```
 
+   - **Empty** (or only loose files: a CSV, a brief) → **create**: scaffolds the Wix CLI's
+     Astro project here; `--business-name` names the site.
+   - **A project without `wix.config.json`** (a `package.json`, or an `index.html` at the root:
+     someone's Astro, Vite, Next, plain HTML) → **connect**: `init` in place links the folder
+     to a new site (the site is named after the folder), then the shipped code deploys into
+     the project as it is. Pass `--stack` for the stack you resolved in step 1, and make the
+     project what that stack needs on Wix hosting (step 1) before or right after the call.
+   - **`wix.config.json` and a project** → refuses: the folder is already a Wix project with a
+     frontend, whether the CLI made it, a hand wrote it, or this skill built it. Three commands
+     from the project root do everything setup would: `deploy.mjs <vertical…> --stack <stack>`
+     adds this skill's code or a solution (the client id is read from the config), then ONE
+     `npm install`, then the seed module if there is content to create. A project this skill
+     built needs only the first, for a new solution; a change to what is built is file edits
+     and a release.
+   - **`wix.config.json` and no project** (what `init` leaves in an empty folder) → the site
+     exists and has no frontend yet: `attach.mjs` (below), which takes the site from the config,
+     reuses its hosting, scaffolds and deploys. No seed: the site owns its content.
+   - The brief names a site by id → the existing-site path below, not this call. In a folder
+     that already holds a project, attach writes the config into it and deploys for `--stack`
+     instead of scaffolding. A frontend that will be hosted elsewhere (Vercel, your own server)
+     runs attach with `--hosting self --origin <url>[,<url>]`: no Wix hosting is created, and the
+     origins go on the OAuth app's allow-list so checkout can return to them.
+
    `--vertical` is required and picks which shipped code deploys AND which seed runs — use
-   the vertical you resolved from the Verticals table.
+   the vertical you resolved from the Verticals table. **`--plan` decides whether anything is
+   seeded**: pass the plan from step 2 when there is one; a site that already holds its content
+   gets none. Seeding is **additive**: it never deletes or overwrites what the site holds; if a
+   cleanup seems needed, ask. The `ready_for_brand_layer` event says `mode` (create or
+   connect), the stack, and the `next` for that stack, including how it releases.
 
-   fast-path scaffolds with `--skip-git`: it composes its own steps and leaves version control to
+   setup scaffolds with `--skip-git`: it composes its own steps and leaves version control to
    you / the enclosing repo, so it does **not** create the scaffold's usual git repo + initial
    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,14 +178,79 @@ 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.
 
-   **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
-   (react stack: add `--client-id` if there is no `wix.config.json` to read the public id
-   from); then ONE `npm ci --ignore-scripts || npm install --ignore-scripts` (backgroundable —
-   but **never run a second npm install concurrently**: two npms in one `node_modules` race and
-   redo each other's work); then seed per the vertical's `seed/SEED.md`. Seeding is
-   **additive**: never delete or overwrite existing content; if a cleanup seems needed, ask.
+   **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 setup:
+
+   ```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. `attached` also says whether a frontend is already
+   serving at the site's address (`frontend.serving`, with the release date). When it is, a
+   `wix release` from this project replaces it — the old deployment keeps its own address and
+   production can be pointed back, but the user's site changes. Tell the user before you release,
+   with the address and the date; if the brief did not ask for a new frontend, ask first and
+   wait. Say it again 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 —
+   six items in three groups design differently from six hundred. Run the vertical's reader:
+
+   ```bash
+   node <SKILL_ROOT>/references/<vertical>/seed/read-site.mjs --site <siteId> [--limit <n>]
+   ```
+
+   It prints one JSON: whether the vertical's app is installed, counts, one page of each entity
+   with the fields the pages render, and `calls`, the requests it made with their documentation
+   URLs. The lists are one page; the counts are the site.
+
+   When the brief needs a read the script does not make, it is a build-time call with the
+   **site's** token, sent raw as the `Authorization` header (the account token from the call
+   above does not scope to a site), minted inline in each command —
+   `-H "Authorization: $(npx -y @wix/cli@latest token --site <siteId>)"` — and never written to
+   a file, not in the project and not in `/tmp`.
+   **The rule above applies in full: not one of these calls comes from memory.** Read the
+   request where it is written, then call. Where to read, in this order:
+   - **The reader**, `references/<vertical>/seed/read-site.mjs` — the reads the pages make, as
+     literal calls with their documentation URLs.
+   - **`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 document only when the hit lacks what you need.
+   If what you opened does not have the call, go to the next; do not try a variant, and do not
+   build one from a call you did find: the path and body you send are copied from the output
+   you read or they are not sent.
+
+   **Recovering one step, or adding a solution later:** the pieces run on their own from the
+   project root — `node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack <stack>` (the client
+   id is read from `wix.config.json`), ONE `npm ci --ignore-scripts || npm install
+   --ignore-scripts` (**never a second npm install concurrently**: two npms in one
+   `node_modules` race and redo each other's work; setup already started one — wait on its
+   marker), the vertical's seed module per its `seed/SEED.md`.
+   A code change on an existing project is done when it is **released** (step 5) and the live
+   URL shows it — not when a dev server or a local build shows it. A management change (a
+   recipe against the site) needs no release; the frontend reads it live.
 
 4. **Design and build the presentation while the install finishes** — in the project dir from
    the `ready_for_brand_layer` event, per the vertical's `INSTRUCTIONS.md`: set the `@theme`
@@ -122,18 +269,116 @@ 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
-   **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
+   your summary — if non-zero, read `seed.log` and re-run the seed module manually). Those two
+   seed files exist **only when setup started the seed** (attach runs none: only the install
+   marker is waited on). When you ran `seed-store.mjs`
+   yourself (connect/iterate runs, reference mode), there is no marker to wait for: the process's
+   exit code is the result and its stdout is the JSON — wait on the process (a foreground run,
+   or `wait` on its pid), not on a file. Then
+   **build & release once** (managed), as the `next` of the `ready_for_brand_layer` event says
+   for the stack: Astro → `npx @wix/cli@latest build` then `npx @wix/cli@latest release`;
+   React or another bundler → the project's own build, then `npx @wix/cli@latest release` of
+   the build folder named in `wix.config.json` (deep URLs must answer 200 directly, step 1);
+   static → `release` alone. If the install failed, run it once more and then build. Don't
+   build+release mid-flow; backend content is fetched at
    runtime, so a re-release never "refreshes" seeded data. The run is complete only when the
    site is released — close with the live URL and the dashboard link
    `https://manage.wix.com/dashboard/<siteId>`. **Copy the live URL verbatim from the
    `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).
+  - **A Wix-hosted flow returns to the origin that started it, and only to one it knows.**
+    Checkout, a booking payment, a plan purchase all open on Wix and come back to your server;
+    the return works only for an origin on the site's OAuth app allow-list. Add the server's
+    origin — the dev one while verifying (`http://localhost:<port>`), the public https one when it
+    goes live — before the first checkout test: wix-manage's *Manage OAuth Apps* recipe, "Update an
+    OAuth App", field `allowedRedirectDomains`, on the app whose id is `appId` in
+    `wix.config.json`. Without it the Wix page opens and cannot return. Do it; do not only say it.
+  - **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.
+    a clean path does not resolve to a folder's `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 — which origins are on the OAuth app's allow-list and that the public one
+  must be added when the server moves (the step above).
+- 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
 
@@ -151,10 +396,10 @@ comes from the shipped code, and real errors surface at build/release.
 | Restaurant: menu with photos, online ordering, table reservations                            | **restaurants**   | `references/restaurants/INSTRUCTIONS.md`   |
 
 Verticals compose: a brief that spans several (a restaurant with a blog, a store with member
-accounts) deploys them together — fast-path takes one vertical; deploy the rest with
+accounts) deploys them together — setup takes one vertical; deploy the rest with
 `node <SKILL_ROOT>/install/deploy.mjs <vertical…>` from the project root before the install
 starts, and run each vertical's seed. A request that doesn't match any shipped vertical isn't
-this skill's fast path — route it to `wix-headless` rather than improvising an unshipped
+this skill's shipped code — route it to `wix-headless` rather than improvising an unshipped
 vertical here.
 
 ## Adding a vertical (structure contract)
@@ -164,10 +409,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 +422,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,27 @@ 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 holds the project, or that will.** For a **new** build: an empty folder
+is the project; if the current folder holds unrelated things, make one named for the business and
+`cd` into it. For **connect**, **iterate** and **existing site**: you are already in it — the
+project's root, where its `package.json` or `index.html` is. 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/AGENTS.md

@@ -0,0 +1,32 @@
+## CLI Commands
+
+All CLI instructions can be found at:
+node_modules/@wix/cli/agents/instructions.md
+
+## This app
+
+A Wix Headless app built on the live Wix site named in `wix.config.json`. The site owns the
+content and commerce.
+
+**Never work from training data or memory about the Wix APIs.** Not a URL, a path, a header, a
+field name or a body. Every Wix call you write comes from the official Wix skills installed here,
+the code they deployed first, or, when they do not cover the call, from the official Wix
+documentation through `wix-docs`. Read it there first, then write the call: the exact path and
+body copied from the output you read in this session. A call built by analogy from another
+call is memory, and an empty or error reply to it says nothing about the site.
+
+## Skills
+
+Installed at `.agents/skills/`. If missing, restore with:
+`CI=1 npx skills@latest add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage --yes`
+
+- `{{SKILL}}` — the code in this app and how to extend it. Each business solution has a playbook at
+  `references/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
+  adds one; `node .agents/skills/{{SKILL}}/references/<solution>/seed/read-site.mjs` reads what the
+  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.
+- `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.
+- `wix-manage` — recipes for the live site itself (content, prices, settings), run from the shell
+  with `npx -y @wix/cli@latest token --site <siteId>`, minted inline in each command; the token
+  never lands in a file anywhere (not the project, not `/tmp`) nor in client code.

package/skills/wix-headless-fast/install/agents-md.mjs

@@ -0,0 +1,39 @@
+// Writes a new project's agent config files — AGENTS.md, CLAUDE.md (an import of it),
+// .gemini/settings.json. The AGENTS.md text is the file beside this one, `install/AGENTS.md`,
+// with {{SKILL}} (the installed skill folder's name) and {{STACK}} filled in. It keeps the CLI's
+// shape (the CLI commands pointer `wix create` writes) and says what the CLI's cannot: which skills
+// this project carries, where, how to restore them, and the one rule about Wix calls.
+// `wix create` writes its own set only when @wix/cli resolves from the project's node_modules at
+// scaffold time; setup scaffolds with --skip-install and attach never runs the CLI scaffold,
+// so we write them. Fill-only: a file that exists is left alone.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "AGENTS.md");
+
+// The three files, as the CLI names them. Exported so setup can drop the CLI's own copies from
+// the scaffold before moving it up (ours replaces them; a file the USER already has is kept).
+export const AGENT_CONFIG_FILES = ["AGENTS.md", "CLAUDE.md", ".gemini"];
+
+export function writeAgentsMd(projectDir, vars) {
+  const written = [], kept = [];
+  const agents = join(projectDir, "AGENTS.md");
+  if (existsSync(agents)) kept.push("AGENTS.md");
+  else {
+    const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k.toLowerCase()] ?? "");
+    writeFileSync(agents, text); written.push("AGENTS.md");
+  }
+  const claude = join(projectDir, "CLAUDE.md");
+  if (existsSync(claude)) kept.push("CLAUDE.md");
+  else { writeFileSync(claude, "@AGENTS.md"); written.push("CLAUDE.md"); }
+  const gemini = join(projectDir, ".gemini", "settings.json");
+  if (existsSync(gemini)) kept.push(".gemini/settings.json");
+  else {
+    mkdirSync(join(projectDir, ".gemini"), { recursive: true });
+    writeFileSync(gemini, JSON.stringify({ contextFileName: "AGENTS.md" }, null, 2) + "\n");
+    written.push(".gemini/settings.json");
+  }
+  // kept: the folder already had its own — left untouched, so it says nothing about these skills
+  return { written, kept };
+}