@wix/agent-skills 1.21.0 → 1.22.0

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

@@ -0,0 +1,76 @@
+# 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. `<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/reference-mode.md

@@ -0,0 +1,97 @@
+# 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.
+
+- **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

@@ -20,9 +20,12 @@ 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.
 - `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

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,19 @@
 // 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 { 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) => {
@@ -77,9 +78,7 @@ const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wi
 const hasProject = has("package.json") || has("index.html");
 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 +245,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 +270,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 +281,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/deploy.mjs

@@ -43,21 +43,25 @@ import {
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { templatesDir } from "./templates.mjs";
+import { syncLockRoot } from "./lock.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const REF = join(SKILL_ROOT, "references");
+// The shipped code: the repository's templates/ (a checkout, the cache, or fetched now).
+const REF = templatesDir();
 const PROJECT = process.cwd();
 const SRC = join(PROJECT, "src");
 const CONFIG_TS = join(SRC, "wix", "config.ts");
 const PKG_JSON = join(PROJECT, "package.json");
 
-// The vertical registry: every directory under references/ that ships an app/ is a vertical.
+// The vertical registry: every directory under templates/ that ships an app/ is a vertical.
 const VERTICALS = readdirSync(REF, { withFileTypes: true })
   .filter(
     (d) =>
       d.isDirectory() &&
       existsSync(join(REF, d.name, "app")) &&
-      d.name !== "shared",
+      d.name !== "shared" &&
+      d.name !== "blank",
   )
   .map((d) => d.name);
 
@@ -73,8 +77,6 @@ const SHARED_DEPS = {
 };
 const CAPABILITY_DEPS = {
   "media-upload": {
-    // All shipped Astro locks already carry @wix/media >= 1.0.271 transitively. Keep this
-    // range compatible with them, then promote it to a root lock dependency below.
     "@wix/media": "^1.0.271",
     "@wix/essentials": "^1.0.10",
   },
@@ -179,7 +181,7 @@ const flagArgs = new Set(
 );
 const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
 
-const result = { stack, verticals: [], skillRoot: SKILL_ROOT };
+const result = { stack, verticals: [], skillRoot: SKILL_ROOT, templates: REF };
 
 if (!["astro", "react", "lib", "static"].includes(stack)) {
   console.log(
@@ -362,13 +364,6 @@ if (result.verticals.length && existsSync(PKG_JSON)) {
   if (added.length)
     writeFileSync(PKG_JSON, JSON.stringify(pkg, null, 2) + "\n");
   result.depsAdded = added.map(([name]) => name);
-  if (added.length)
-    result.note = [
-      result.note,
-      "run `npm install --ignore-scripts` to pick up depsAdded",
-    ]
-      .filter(Boolean)
-      .join("; ");
 } else if (result.verticals.length) {
   result.depsAdded = [];
   result.note = [
@@ -379,54 +374,20 @@ if (result.verticals.length && existsSync(PKG_JSON)) {
     .join("; ");
 }
 
-// ---- shipped lockfile (single vertical only) ------------------------------------------------------
-// A pre-resolved package-lock.json covering the scaffold + this vertical's deps ships at
-// references/<vertical>/lock/<stack>/package-lock.json. Placing it lets `npm ci` skip the whole
-// resolution phase (seconds instead of minutes). URLs are canonical registry.npmjs.org form —
-// npm substitutes the locally configured registry (mirrors/proxies) at fetch time. Placed only
-// when the project has no lock of its own; if it ever drifts out of sync, `npm ci` fails fast
-// and the `|| npm install` fallback self-heals.
+// ---- the project's lockfile ---------------------------------------------------------------------
+// A project created from a composed template (templates/<vertical>/project) carries that
+// template's package-lock.json, so `npm ci` installs it without resolving. When this run added
+// dependencies to package.json, the lock's root entry is brought in line where the tree already
+// holds the package (install/lock.mjs); anything the tree lacks makes `npm ci` fail fast and the
+// `|| npm install` fallback resolve it. A project without a lock installs with `npm install`.
 const PROJECT_LOCK = join(PROJECT, "package-lock.json");
-if (
-  result.verticals.length === 1 &&
-  existsSync(PKG_JSON) &&
-  !existsSync(PROJECT_LOCK)
-) {
-  const shippedLock = join(
-    REF,
-    result.verticals[0],
-    "lock",
-    stack,
-    "package-lock.json",
-  );
-  if (existsSync(shippedLock)) {
-    cpSync(shippedLock, PROJECT_LOCK);
-    if (uploadPolicies.length) {
-      // The supplied per-vertical lock already resolves Media + Essentials transitively. Add
-      // them to its root package entry too, so npm ci accepts package.json's new direct
-      // dependency without falling back to a slow dependency-resolution install.
-      const lock = JSON.parse(readFileSync(PROJECT_LOCK, "utf8"));
-      lock.packages ??= {};
-      lock.packages[""] ??= {};
-      lock.packages[""].dependencies ??= {};
-      const rootDeps = lock.packages[""].dependencies;
-      for (const [name, range] of Object.entries(CAPABILITY_DEPS["media-upload"])) {
-        if (!lock.packages?.[`node_modules/${name}`]) {
-          result.lockCapability = `UNPATCHED — supplied lock lacks ${name}; npm install will resolve it`;
-          break;
-        }
-        rootDeps[name] = range;
-      }
-      writeFileSync(PROJECT_LOCK, JSON.stringify(lock, null, 2) + "\n");
-      if (!result.lockCapability) result.lockCapability = "media_upload_promoted";
-    }
-    result.lockDeployed = true;
-    result.note = [
-      result.note,
-      "install with `npm ci --ignore-scripts || npm install --ignore-scripts`",
-    ]
-      .filter(Boolean)
-      .join("; ");
+if (result.verticals.length && existsSync(PKG_JSON)) {
+  if (existsSync(PROJECT_LOCK)) {
+    const sync = syncLockRoot(PROJECT);
+    if (sync && (sync.promoted.length || sync.missing.length)) result.lock = sync;
+    result.note = [result.note, "install with `npm ci --ignore-scripts || npm install --ignore-scripts`"].filter(Boolean).join("; ");
+  } else if (result.depsAdded?.length) {
+    result.note = [result.note, "run `npm install --ignore-scripts` to pick up depsAdded"].filter(Boolean).join("; ");
   }
 }
 

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

@@ -0,0 +1,55 @@
+// Keep a project's package-lock.json valid for `npm ci` after package.json gained dependencies.
+// `npm ci` refuses a lock whose root entry disagrees with package.json. When the dependency deploy
+// added is already in the lock's tree (pulled in by something else), declaring it in the root entry
+// too is all `npm ci` needs; a dependency the tree lacks is left for `npm install` to resolve.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const parse = (v) => {
+  const m = String(v).match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? m.slice(1).map(Number) : null;
+};
+const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+// The ranges deploy writes: exact, ^x.y.z, ~x.y.z, >=x.y.z. Anything else is "not known to fit".
+export function satisfies(version, range) {
+  const v = parse(version);
+  const m = String(range).trim().match(/^(\^|~|>=)?\s*v?(\d+\.\d+\.\d+)/);
+  if (!v || !m) return false;
+  const r = parse(m[2]);
+  const op = m[1] ?? "";
+  if (op === "") return cmp(v, r) === 0;
+  if (cmp(v, r) < 0) return false;
+  if (op === ">=") return true;
+  if (op === "~") return v[0] === r[0] && v[1] === r[1];
+  // caret: same major; for 0.x, same minor
+  return r[0] > 0 ? v[0] === r[0] : v[0] === 0 && v[1] === r[1];
+}
+
+// Returns null when there is no lock; else {promoted, missing}. Writes the lock only when it changed.
+export function syncLockRoot(projectDir) {
+  const lockPath = join(projectDir, "package-lock.json");
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(lockPath) || !existsSync(pkgPath)) return null;
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+  lock.packages ??= {};
+  const root = (lock.packages[""] ??= {});
+  const promoted = [], missing = [];
+  let changed = false;
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(pkg[field] ?? {})) {
+      if (root[field]?.[name] === range) continue;
+      const inTree = lock.packages[`node_modules/${name}`];
+      if (inTree && satisfies(inTree.version, range)) {
+        (root[field] ??= {})[name] = range;
+        promoted.push(name);
+        changed = true;
+      } else {
+        missing.push(name);
+      }
+    }
+  }
+  if (changed) writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
+  return { promoted, missing };
+}

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

@@ -9,8 +9,9 @@
 //     this skill's code or a solution to it, then one install, then the seed if there is content.
 //   - a project but no `wix.config.json` (a package.json, or an index.html at the root) → CONNECT:
 //     `npm create @wix/new@latest init` in place creates the site and the config, then deploy.
-//   - otherwise (empty, or loose files such as a CSV or a brief) → CREATE: scaffold the Wix CLI's
-//     Astro template and place it in the current directory (`--business-name` required).
+//   - otherwise (empty, or loose files such as a CSV or a brief) → CREATE: `wix create` with the
+//     vertical's composed template (templates/<vertical>/project: the CLI's blank scaffold with the
+//     vertical deployed and a lockfile), placed in the current directory (`--business-name` required).
 //
 // The script reads file markers only (wix.config.json, a package.json or index.html); everything
 // else is the agent's call: when connecting, `--stack` is required and comes from SKILL.md step 1,
@@ -22,10 +23,11 @@
 // steps — the dependency install and the seed — running detached in the background (logs and
 // completion markers in the final event), so the caller can build the brand layer while they finish.
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AGENT_CONFIG_FILES, writeAgentsMd } from "./agents-md.mjs";
+import { listVerticals, templatesDir } from "./templates.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -47,9 +49,10 @@ const vertical = flag("vertical");
 const stackFlag = flag("stack");
 // Opt-in: keep a CREATE's project in a subfolder instead of the current directory.
 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);
+// 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 knownVerticals = listVerticals(TEMPLATES);
 const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}> [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--subfolder]`;
 // --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong seed.
 if (!vertical) fail("args", usage);
@@ -92,7 +95,13 @@ if (mode === "create") {
   if (existsSync(join(projectDir, "wix.config.json"))) {
     emit("scaffold_skipped", { reason: "project already exists", folder: folderName });
   } else {
-    emit("scaffolding", { folder: folderName });
+    // The composed template: the CLI copies it in place of its blank one, creates the site and
+    // writes wix.config.json; the vertical's code and its lockfile arrive with it. Any other
+    // stack takes the CLI's blank Astro scaffold, as before, and deploy below adds the code.
+    // The composed project is the one part of the templates a project's repository does not keep;
+    // a committed copy fetches it here, at the commit the rest came from.
+    const template = stack === "astro" ? join(templatesDir({ need: `${vertical}/project` }), vertical, "project") : null;
+    emit("scaffolding", { folder: folderName, template });
     const scaffold = spawnSync(
       "npm",
       // --skip-git: this wrapper composes its own steps and leaves version control to
@@ -102,7 +111,8 @@ if (mode === "create") {
       // same reason: deps install in a detached step below.
       ["create", "@wix/new@latest", "--", "headless",
        "--folder-name", folderName, "--business-name", businessName,
-       "--site-template", "--skip-install", "--skip-git", "--no-publish"],
+       "--site-template", "blank", ...(template ? ["--template-path", template] : []),
+       "--skip-install", "--skip-git", "--no-publish"],
       { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
     );
     if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
@@ -123,12 +133,22 @@ if (mode === "create") {
 }
 const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
 const siteId = wixConfig.siteId ?? wixConfig.projectId;
+// Static: `wix release` uploads the output folder whole, so the project root (config, plan, seed
+// output, the skills) must not be it. The site lives in site/: the config points there and the REST
+// layer deploys into it; the pages, styles and assets are the agent's to move (the `next` says so).
+const STATIC_OUT = "site";
+if (stack === "static") {
+  wixConfig.site = { ...(wixConfig.site ?? {}), outputDirectory: `./${STATIC_OUT}` };
+  writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify(wixConfig, null, 2) + "\n");
+}
 emit(mode === "create" ? "scaffolded" : "connected", { folder: folderName ?? cwd, siteId, stack });
 
-// ---- 2 · deploy shipped code + deps + lockfile ---------------------------------------------------
+// ---- 2 · deploy shipped code + deps ---------------------------------------------------------------
+// A CREATE from the composed template already holds the code and the lock: deploy adds nothing and
+// reports the project; a CONNECT gets the code and its dependencies here.
 const deploy = spawnSync(
   "node",
-  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(planPath ? ["--plan", resolve(planPath)] : [])],
+  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
   { cwd: projectDir, encoding: "utf8", timeout: 60_000 },
 );
 if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
@@ -196,7 +216,7 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
 // additive: it never deletes or overwrites what the site holds.
 let seed = null;
 if (planPath) {
-  const seedDir = join(SKILL_ROOT, "references", vertical, "seed");
+  const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
     : undefined;
@@ -218,7 +238,7 @@ const release = {
   astro: "npx @wix/cli@latest build, then npx @wix/cli@latest release",
   react: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (what Wix hosting serves and how routes must be shaped: SKILL.md step 1)",
   lib: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (SKILL.md step 1)",
-  static: "npx @wix/cli@latest release — no build; wix.config.json site.outputDirectory points at the folder the pages live in",
+  static: `npx @wix/cli@latest release — no build; it uploads ${STATIC_OUT}/ whole (wix.config.json site.outputDirectory), so the pages, styles and assets move into ${STATIC_OUT}/ first and import the modules from ./js/wix/ there; the root keeps the config, the plan, the seed output and the skills`,
 }[stack];
 emit("ready_for_brand_layer", {
   mode,