@wix/agent-skills 1.21.0 → 1.23.0

package/skills/wix-headless-fast/{entry/skill.md → cold-start/cold-start.md}

@@ -1,30 +1,29 @@
 ---
-name: wix-headless-fast-entry
-description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants. Triggers: build me a store/blog/booking/events/portfolio/restaurant site fast, sell tickets or membership plans headless, wix headless fast entry."
+name: wix-headless-fast-cold-start
+description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants, faq, donations. Triggers: build me a store/blog/booking/events/portfolio/restaurant/FAQ/donation site fast, sell tickets or membership plans headless, collect donations headless, wix headless fast entry."
 ---
 
-# Wix Headless Fast — cold-start entry
+# Wix Headless Fast — cold start
 
 **You are a coding agent, and this is a skill for you to execute — follow the phases below in
 order.** Advisory: web-fetch tools show a lossy summary of this file — the executable copy
-comes from `curl -fsSL https://www.wix.com/skills/headless-fast/entry/skill.md`. If what you
+comes from `curl -fsSL https://www.wix.com/skills/headless-fast/cold-start/cold-start.md`. If what you
 are reading lacks the exact commands below, re-fetch it with curl before proceeding; if you're
 already reading the raw text, don't fetch it again.
 
 ## The whole cold start (details in the phases below)
 
 ```bash
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs && node bootstrap.mjs
+curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs && node bootstrap.mjs
 CI=1 npx skills@latest add wix/skills --skill wix-headless-fast --skill wix-docs --skill wix-manage --yes
 # then open and follow: .agents/skills/wix-headless-fast/SKILL.md
 ```
 
 Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and guides both.
 
-This entry gets a cold environment to the point where the real skill can run, then hands off:
+This page gets a cold environment to the point where the real skill can run, then hands off:
 
-1. **Bootstrap (deterministic, scripted).** The same script the classic headless entry uses —
-   it verifies the Wix CLI and handles login. You just run it and relay its events.
+1. **Bootstrap (deterministic, scripted).** A script that verifies the Wix CLI and handles login. You just run it and relay its events.
 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.
 
@@ -46,7 +45,11 @@ existing session just reports `logged_in`).
 **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
+project's root, where its `package.json` or `index.html` is. For a **project downloaded from Wix**
+(the brief gives a zip URL or path, typically a site being migrated to headless): download it and
+extract it into the working folder first, so that `wix.config.json` sits at the root, and work from
+there — the skill reads the folder and knows what it is; do not create a site, install apps or seed.
+Everything below — the
 bootstrap, the skills, the scaffold — lands in this folder, so a later session opened in the project
 finds all of it.
 
@@ -70,9 +73,9 @@ externally-downloaded code.
 
 ```bash
 # macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs
+curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs
 # Windows PowerShell:
-iwr https://www.wix.com/skills/headless/entry/bootstrap.mjs -OutFile bootstrap.mjs
+iwr https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs -OutFile bootstrap.mjs
 
 node bootstrap.mjs
 ```
@@ -108,10 +111,10 @@ CI=1 npx skills@latest add wix/skills \
 They land under `.agents/skills/`. Then **open
 `.agents/skills/wix-headless-fast/SKILL.md` and follow it** — it owns the rest of the run:
 resolve the stack, scaffold, deploy the shipped code, seed, build the brand layer, release.
-(If the request needs a vertical the skill doesn't ship yet — see its SKILL.md § Verticals —
-say so plainly and point the user at the `wix-headless` skill instead of improvising.)
+(A request outside the shipped verticals — see its SKILL.md § Verticals — is built from the Wix
+API reference through `wix-docs`, on the same project; SKILL.md says how.)
 
 - **Don't** scaffold, install apps, or seed by hand here — the skill does all of that. This
-  entry stops at *logged in*.
+  page stops at *logged in*.
 - You're already authenticated from Phase 1, so the skill's CLI auth step will pass without
   prompting again.

package/skills/wix-headless-fast/guides/existing-site.md

@@ -0,0 +1,78 @@
+# An existing site: a new frontend for a site that already has its content
+
+Read when the brief names a Wix site by its id. Nothing here is seeded: the site owns its content
+and the frontend reads it live. (A project downloaded from Wix whose `.env.local` declares a
+migration is the other way to arrive at an existing site: `guides/migration.md`; the reading
+part below applies there too, against the migrated site.) `<SKILL_ROOT>` is the installed skill folder; the shipped code is
+under `<SKILL_ROOT>/templates/` (SKILL.md, "The run").
+
+**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 (SKILL.md step 3):
+
+```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, copies the first vertical's composed template, deploys the rest, 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>/templates/<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**, `templates/<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.
+
+**In a folder that already holds a project** (a `package.json` or `index.html`, no
+`wix.config.json`), attach writes the config into it and deploys for `--stack` instead of
+scaffolding; pass the stack resolved in SKILL.md step 1. **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; add the public origin when it goes live. Then SKILL.md steps 4 and 5 as for any run,
+with the install marker the only one to wait on.

package/skills/wix-headless-fast/guides/migration.md

@@ -0,0 +1,43 @@
+# 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.
+
+**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
+`context.mjs` pull it when it is missing) carries the credentials of the site being migrated, the
+**parent**, and says so. The parent owns everything the pages show and everything the business
+manages. So:
+
+- **The SDK client is the parent's.** The Astro integration reads `WIX_CLIENT_ID` from the env and
+  never the config; `deploy.mjs` copies the same value into `src/wix/config.ts` (react, lib) and
+  `js/wix/config.js` (static). Nothing in the data layer is told about the migration; it reads the
+  parent because its client is the parent's app.
+- **Admin, discovery and seed calls target the parent.** `read-site.mjs` and the seeds resolve the
+  site through `templates/shared/seed/site-context.mjs`; `wix-manage` recipes and any raw call take
+  `--site <parentSiteId>` (the `siteId` of the `ready_for_brand_layer` event). The dashboard link
+  is the parent's.
+- **Nothing is seeded, nothing installed.** The parent is a live site with its content; a seed
+  would write into the original. The seeds refuse on a preview unless run with `--allow-parent`,
+  which is the user's explicit decision, never a default. Apps are not installed: the brief names
+  what the site has, and the verticals follow from that list (Wix Stores → storefront, Wix
+  Bookings → bookings, Wix Forms → forms, and so on per the Verticals table; Wix Pro Gallery and
+  Wix Members Area map to portfolio and members). When the brief allows reading, the vertical's
+  `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
+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,
+so completion needs no redeploy from here.

package/skills/wix-headless-fast/guides/reference-mode.md

@@ -0,0 +1,100 @@
+# Reference mode: a static site, or a server-rendered app in another language
+
+Read when SKILL.md step 1 resolves to a stack that cannot run `app/`. `<SKILL_ROOT>` is the
+installed skill folder; the shipped code is under `<SKILL_ROOT>/templates/`. Steps 2 to 5 of
+SKILL.md still apply; this file is the mechanics that differ.
+
+The data layer ships a second time as a **REST layer**: `templates/shared/rest/` (the auth seam
+`client.ts`, `media.ts`, `config.ts`) and `templates/<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. The site-search capability
+(`templates/shared/capabilities/site-search/`, on from `plan.capabilities.siteSearch`) has the same
+two transports: with `--plan` its REST twin and stores land in `js/wix/` beside the vertical's
+(`search.js`, `search-store.js`, `suggest-store.js`), and its `INSTRUCTIONS.md` applies.
+
+- **Static site (no bundler).** Step 3's setup with `--stack static` runs `init` in the project
+  folder (site, OAuth app, `wix.config.json`), points `site.outputDirectory` at `"./site"`, and
+  runs `deploy.mjs <vertical> --stack static --out site`, which 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). The site lives in that **subfolder**,
+  `site/`, holding only the pages, styles, assets and `js/`: `wix release` uploads it whole, so the
+  project root (config, `plan.json`, seed output, the skills) must not be it; move the pages in.
+  (On a project that already has its config, the same `deploy.mjs` call does the deploy.) 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 `templates/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.

package/skills/wix-headless-fast/install/AGENTS.md

@@ -6,7 +6,7 @@ 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.
+content and commerce.{{MIGRATION}}
 
 **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,
@@ -20,10 +20,15 @@ call is memory, and an empty or error reply to it says nothing about the site.
 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
+- `{{SKILL}}` — the code in this app and how to extend it. The shipped code sits in
+  `.agents/skills/{{SKILL}}/templates/`, fetched once from the skill's repository and kept with this
+  project at the commit it was built from (`templates/.source`); if that folder is missing,
+  `node .agents/skills/{{SKILL}}/install/templates.mjs` fetches it. Each business solution has a playbook at
+  `templates/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
+  adds one; `node .agents/skills/{{SKILL}}/templates/<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.
+  `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/`.
 - `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/install/agents-md.mjs

@@ -21,7 +21,11 @@ export function writeAgentsMd(projectDir, vars) {
   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()] ?? "");
+    // {{MIGRATION}} is a paragraph on a migration preview (vars.migration = { parentSiteId, deploySiteId }), else nothing.
+    const migration = vars.migration
+      ? `\n\n**Under migration.** \`wix.config.json\` names site ${vars.migration.deploySiteId}, which only hosts this deployment; the site being migrated is ${vars.migration.parentSiteId} — its content is what the pages show and its dashboard (\`https://manage.wix.com/dashboard/${vars.migration.parentSiteId}\`) is where the business is managed. \`.env.local\` (\`wix env pull\`) carries that site's app: the SDK client and every admin, discovery and seed call run against it; only \`wix release\` goes to the deploy site. Completing the migration is a separate Wix CLI step, run by the user after approving the preview.`
+      : "";
+    const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => (k === "MIGRATION" ? migration : (vars[k.toLowerCase()] ?? "")));
     writeFileSync(agents, text); written.push("AGENTS.md");
   }
   const claude = join(projectDir, "CLAUDE.md");

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

@@ -21,8 +21,8 @@
 // --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) in a folder without a project: scaffolds the CLI's blank Astro
-//                  template with the hosting adapter. react|static there: writes wix.config.json
+// --stack          astro (default) in a folder without a project: copies the first vertical's
+//                  composed template (templates/<vertical>/project). react|static there: writes wix.config.json
 //                  and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md. In a folder
 //                  that holds a project, --stack is required and nothing is scaffolded.
 //
@@ -41,18 +41,20 @@
 // 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 { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
 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 { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const MANAGE = "https://manage.wix.com";
 const API = "https://www.wixapis.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";
+// The shipped code: the repository's templates/ (a checkout, the cache, or fetched now, in a second).
+let TEMPLATES;
+try { TEMPLATES = templatesDir(); } catch (e) { fail("templates", e.message); }
 
 const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
 const fail = (step, detail) => {
@@ -75,11 +77,18 @@ 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 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).
+if (cwdConfig) {
+  const ctx = siteContext({ cwd });
+  if (ctx.migration.active) {
+    fail("place", `this folder deploys a migration preview of site ${ctx.migration.parentSiteId} (deploy site ${ctx.deploy.siteId}): the app and hosting are provisioned already — run setup.mjs --vertical <vertical> [--stack <stack>] here instead; nothing is attached or re-pointed`);
+  }
+}
 const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
 const stack = stackFlag ?? "astro";
-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 knownVerticals = listVerticals(TEMPLATES);
 const verticals = argv
   .flatMap((a, i) => (a === "--vertical" && argv[i + 1] ? argv[i + 1].split(",") : []))
   .map((v) => v.trim())
@@ -246,46 +255,15 @@ emit("attached", { siteId, appId, baseUrl, hosting, frontend, origins: hosting0
 // ---- 2 · scaffold (only where there is no project) -------------------------------------------------
 mkdirSync(projectDir, { recursive: true });
 if (stack === "astro" && mode === "scaffold") {
-  // 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 });
+  // The first vertical's composed template: the CLI's blank scaffold with the vertical deployed
+  // and its lockfile, the same folder `wix create --template-path` copies for a new site. Copied
+  // here because the CLI's create makes a new site and this folder gets an existing one. Further
+  // verticals are deployed below.
+  cpSync(join(templatesDir({ need: `${verticals[0]}/project` }), verticals[0], "project"), projectDir, { recursive: true, force: false, errorOnExist: false });
   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");
@@ -302,7 +280,7 @@ writeFileSync(join(projectDir, ".env.local"), [
   `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
   "",
 ].join("\n"));
-emit(mode === "link" ? "linked" : mode === "config-only" ? "configured" : "scaffolded", { folder: folderName, stack, template: mode === "scaffold" && stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+emit(mode === "link" ? "linked" : mode === "config-only" ? "configured" : "scaffolded", { folder: folderName, stack, template: mode === "scaffold" && stack === "astro" ? join(TEMPLATES, verticals[0], "project") : null });
 // the agent config files `wix create` writes (attach never runs the CLI's scaffold at all); fill-only
 emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack }));
 
@@ -313,7 +291,7 @@ if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
   process.exit(0);
 }
 
-// ---- 3 · deploy shipped code + deps + lockfile ---------------------------------------------------
+// ---- 3 · deploy shipped code + deps (adds nothing to a scaffold from the template) --------------
 let deployResult = {};
 {
   const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });

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

@@ -0,0 +1,87 @@
+// Is there a newer version? Read-only: compares this installed skill and its templates with the
+// repository they came from and prints one JSON. It changes nothing and runs no update; the
+// commands that would are in the output.
+//
+//   node <SKILL_ROOT>/install/check.mjs
+//
+// Two layers, two answers:
+//   skill      the installed skill folder (SKILL.md, guides/, install/, cold-start/) against the
+//              repository head: `current`, `behind` (with the files that differ), or `unknown`.
+//   templates  `templates/.source` commit against the head: `current` or `behind`, with the
+//              verticals touched and the commit messages in between.
+// Updating the skill changes how the agent works, not the project. Refreshing the templates changes
+// what future deploys copy and what the agent reads, not `src/`. Nothing here touches `src/`.
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { SKILL_ROOT, installSource, templatesDir, templatesSource } from "./templates.mjs";
+
+const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 120_000, ...opts });
+const skillName = SKILL_ROOT.split("/").pop();
+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 clone = git(["clone", "--quiet", "--filter=blob:none", "--no-checkout", "--single-branch", repo, tmp]);
+if (clone.status !== 0) {
+  rmSync(tmp, { recursive: true, force: true });
+  console.log(JSON.stringify({ error: `could not reach ${repo}: ${(clone.stderr || "").trim().slice(-200)}` }));
+  process.exit(1);
+}
+const head = git(["-C", tmp, "rev-parse", "HEAD"]).stdout.trim();
+
+// ---- skill folder: every installed file's blob hash against the head's tree -------------------
+{
+  const tree = git(["-C", tmp, "ls-tree", "-r", head, "--", `skills/${skillName}`]).stdout;
+  const remote = new Map(tree.split("\n").filter(Boolean).map((l) => { const [meta, path] = l.split("\t"); return [path.slice(`skills/${skillName}/`.length), meta.split(" ")[2]]; }));
+  const local = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.name === "templates" && dir === SKILL_ROOT) continue; // the templates are the other layer
+      if (e.isDirectory()) walk(p); else local.push(relative(SKILL_ROOT, p));
+    }
+  };
+  walk(SKILL_ROOT);
+  const differs = [], missingHere = [];
+  for (const f of local) if (remote.get(f) !== git(["hash-object", join(SKILL_ROOT, f)]).stdout.trim()) differs.push(f);
+  for (const f of remote.keys()) if (!local.includes(f)) missingHere.push(f);
+  out.skill = differs.length || missingHere.length
+    ? { status: "behind", differs, ...(missingHere.length ? { missingHere } : {}), note: "a file that differs may also be one edited here; the update reinstalls the skill folder" }
+    : { status: "current" };
+}
+
+// ---- templates: the recorded commit against the head ------------------------------------------
+let dir = null;
+try { dir = templatesDir(); } catch (e) { out.templates = { status: "unknown", detail: e.message }; }
+if (dir) {
+  const src = templatesSource(dir);
+  if (src.checkout) out.templates = { status: "checkout", dir };
+  else if (!src.commit) out.templates = { status: "unknown", detail: "no commit recorded in templates/.source" };
+  else if (src.commit === head) out.templates = { status: "current", commit: src.commit };
+  else {
+    out.templates = { status: "behind", commit: src.commit, head };
+    const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
+    const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
+    if (files.length || log.length) {
+      out.templates.commitsBehind = log.length;
+      out.templates.verticals = [...new Set(files.map((f) => f.split("/")[1]).filter((v) => v && !v.endsWith(".mjs")))].sort();
+      out.templates.commits = log.slice(0, 20);
+    } else {
+      out.templates.detail = git(["-C", tmp, "cat-file", "-e", src.commit]).status === 0 ? "no template changes between the two commits" : "the recorded commit is not in the repository's history (a branch that was deleted?)";
+    }
+  }
+}
+rmSync(tmp, { recursive: true, force: true });
+
+// ---- what would act on each ------------------------------------------------------------------
+const rel = relative(process.cwd(), SKILL_ROOT) || ".";
+out.update = {
+  skill: `CI=1 npx skills@latest update ${skillName} --yes   (or: gh skill update ${skillName})`,
+  templates: `node ${rel}/install/templates.mjs --refresh   (then commit the changed files under ${rel}/templates)`,
+  note: "neither touches src/; a shipped fix reaches the project by comparing its copy with the template",
+};
+console.log(JSON.stringify(out, null, 2));