@wix/agent-skills 1.31.1 → 1.31.2

package/package.json

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

package/skills/wix-app/references/STORES_VERSIONING.md

@@ -130,4 +130,4 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 - [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
 - [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.
+For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsMethodSchema` (use `ReadFullDocsArticle` only for prose). Always return the required permission scopes to the user.

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

@@ -106,6 +106,11 @@ paths below are relative to that folder, never assumed under `<SKILL_ROOT>`.
 `node <SKILL_ROOT>/install/check.mjs` says whether the skill or its templates have a newer version
 and prints the update commands; it changes nothing.
 
+Throughout any run, keep the site working at every step so the user can try it as it grows. Steps
+only the site owner can take never hold a flow back: drafted content is live, and anything that
+takes money reaches Wix's checkout before payments are connected. The owner's steps go in the
+closing with their links, as next steps the user can take or ask for.
+
 Throughout any run: if the user asks to send feedback to Wix, complains or gets frustrated, or the
 run hits friction of any kind: anything that cost more turns than it should have, whether or not
 it ended in an error (a confusing error, a doc gap, a seed that had to be re-run, a shipped file
@@ -143,8 +148,9 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
      `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.
+     before deploying, and the site serves every route. The integration's current major
+     (`@wix/astro` 3, as in this skill's templates) requires **Astro 7**: a project on an earlier
+     major moves to 7 first, or is 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
@@ -189,10 +195,13 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    | a frontend, no config (a `package.json`, or `index.html` at the root: someone's Astro, Vite, Next, plain HTML) | **project** → adopt | `init` in place gives it a new, empty site, then deploys; `--stack` from step 1 is required; make the project what that stack needs on Wix hosting (step 1) before or right after | **yes**, from `--plan` |
    | a config whose `.env.local` declares an active editor migration (`EDITOR_MIGRATION_STATUS=ACTIVE`), with or without the blank Astro starter the download carries | **migration** → migrate | the shipped code into the starter (or the composed template around a bare config), deployed with the migrated site's app as the client, the install starts; `ready_for_brand_layer` says `mode: "migrate"`, the parent as `siteId`, the child as `deploySiteId` (`guides/migration.md`) | no, ever |
    | a config, no frontend | **config-only** → refuses | the site exists and has no frontend yet: `attach.mjs` (below) takes the site from the config, reuses its hosting, scaffolds and deploys. That config is what `init` leaves behind, and `init` always creates a site: this site was made for this run and is empty | **yes**: draft the plan as for create, then `attach.mjs --plan` |
-   | a config and a frontend (a `package.json`, or `index.html` inside the folder `site.outputDirectory` names) | **wix-project** → refuses | iterate: never scaffold, `init` or reseed. `deploy.mjs <vertical…> --stack <stack>` adds a solution (the client id comes from `.env.local`, the config as the fallback), then ONE `npm install`; a change is file edits; then release | no |
+   | a config and a frontend (a `package.json`, or `index.html` inside the folder `site.outputDirectory` names) | **wix-project** → refuses | iterate: never scaffold, `init` or reseed. `deploy.mjs <vertical…> --stack <stack>` adds a solution (the client id comes from `.env.local`, the config as the fallback), then one install, `node <SKILL_ROOT>/install/install.mjs` (nothing when `node_modules` already satisfies the lock); a change is file edits; then release | no |
    | a config, a `package.json`, `public/index.html` and no `src/pages/` (a site published through the drop flow, on its Wix Dev Machine) | **static-in-astro** → refuses | the pages stay plain files in `public/`: `deploy.mjs <vertical…> --stack static --out public` puts the REST layer in `public/js/wix/`, the pages are wired in place (reference mode), and no Astro pages are added; release with `build` then `release`, the URL stays | no |
+   | a config and the CLI's blank Astro starter with no work of its own (`wix-astro-blank`, only the blank template's packages: a Dev Machine's never-released site, a bare `wix create`) | **blank-starter** → refuses | `attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json]` on the config's site: the vertical's composed template takes the starter's place (its lockfile with it), the install and the seed start detached; build the brand layer while they run | **yes**, from `--plan`: the site was made for this run and is empty, unless `read-site.mjs` shows content |
    | a config, `index.html` at the root, no `package.json` (a site published through the drop flow and downloaded) | **published-static** | the config's site, no `init`: `site/` becomes the upload, the REST layer deploys into `site/js/wix/`; the `next` says to move the pages, styles and assets in; release keeps the URL | no |
 
+   A folder no row names is **wix-project**: the fill-only path — never scaffold, `init`, reseed or delete; deploy, edit, release. A wrong guess costs a slower run, never the user's work.
+
    **Who decides the seed: where the site came from, never the brief's wording.** A site made
    for this run is empty by construction, so it is always seeded — with the brief's content when
    it supplies or describes any, otherwise with demo content the agent drafts per the vertical's
@@ -232,7 +241,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    It emits one JSON event per line and returns in **~35s**: **scaffolds** the project from the
    vertical's composed template (`wix create` copies it: the code and its lockfile arrive with
    the scaffold), **deploys** whatever the folder still lacks (patching `package.json` with every
-   dependency the code imports), then **starts two detached background jobs** — the dependency install (`npm ci --ignore-scripts || npm install --ignore-scripts`)
+   dependency the code imports), then **starts two detached background jobs** — the dependency install (`install/install.mjs`: nothing when `node_modules` already satisfies the lock, `npm install --ignore-scripts` over a tree that is there, else `npm ci --ignore-scripts || npm install --ignore-scripts`)
    and the **seed** — whose logs and completion markers are in the events. The final
    `ready_for_brand_layer` event carries the project dir, siteId, ready-made dashboard links,
    and both markers. Relay notable events. On an `error` event, recover just that step via the
@@ -240,8 +249,8 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
 
    **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
+   id is read from `wix.config.json`), ONE `node <SKILL_ROOT>/install/install.mjs`
+   (**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
@@ -266,7 +275,7 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    `templates/shared/CUSTOM_OPERATIONS.md` before writing it. Use one documented path and
    implement it; do not reverse-engineer SDK internals.
 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
+   (`.install-exit`, containing `0`) 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). Those two
    seed files exist **only when setup started the seed** (attach runs none: only the install

package/skills/wix-headless-kit/guides/api-run.md

@@ -3,10 +3,17 @@
 Read when the commands this skill is built on cannot run where you are, or stopped: your shell
 can't reach Wix, there is no shell, or the install, the
 CLI or the login is blocked. Wix is then reachable through the Wix MCP: every call below is an
-`ExecuteWixAPI` call, and files reach the site through the upload recipe. It walks the run of
+`ExecuteWixAPI` call, and files reach the site through the upload recipe. With no Wix MCP tools in
+your tool list (a plugin's skills can be on disk while its Wix connector is not connected), ask the
+user to connect Wix to this chat first. It walks the run of
 SKILL.md step by step and names, for each, the Wix API call the CLI or the script performs and the
 file beside this skill that carries the contract; where a script can run where you are, it says so.
 
+As in SKILL.md's run, keep the site working at every step so the user can try it as it grows.
+Steps only the site owner can take never hold a flow back: drafted content is live, and anything
+that takes money reaches Wix's checkout before payments are connected. The owner's steps go in the
+closing with their links, as next steps the user can take or ask for.
+
 ## Where these skills are
 
 This skill is one of a set, and the guide reads from three of them:
@@ -25,13 +32,25 @@ This skill is one of a set, and the guide reads from three of them:
   exact shape before writing a call.
 
 Installed, they sit beside each other wherever your client keeps them: under `.agents/skills/` after
-`npx skills add`, or in a plugin's folder. Read them from disk when they are there. Online, they are
-published alongside each other under the same names (the registry also serves each without its
-`wix-` prefix, `headless-templates` for `wix-headless-templates`, which is the `base` its manifest
-shows; both forms resolve), each with a manifest of its files, and in the
+`npx skills add` or a similar skills folder, or in a plugin's folder. A skill your client offers you
+by name is read from there, or through the client's skill tool when it is served rather than a file,
+with no install, clone or online read. List them first, through that tool or the folder: a catalog
+shown at the start can leave skills out. Online, they are published alongside each other under the
+same names (the registry also serves each without its `wix-` prefix, `headless-templates` for
+`wix-headless-templates`, which is the `base` its manifest shows; both forms resolve), and in the
 `wix/skills` repository on GitHub under `skills/{skill}/`; a sandbox that reaches GitHub has the
-whole set on disk from a clone. Online pages are read with the Wix MCP's `ReadFullDocsArticle`
-when it is connected: a client's web fetch may open only URLs the user gave or a search returned.
+whole set on disk from a clone. Online pages are read with the Wix MCP's `ReadFullDocsArticle` when
+it is connected: a client's web fetch may open only URLs the user gave or a search returned.
+
+Online, a skill's files are found through its manifest,
+`https://www.wix.com/skills/{skill}.manifest.json` (for the templates,
+`headless-templates.manifest.json`): every file it holds, by path, with its size in bytes. A
+folder's URL lists its files, and `<folder>/_content` returns them in one response. Open it once
+before the first file and take each path from it: the files this guide names by pattern
+(`{solution}/rest/*.ts`, `*-core.ts`), and the files an import points to. A path the manifest
+doesn't list is a wrong path; find the file there before writing anything in its place. A copy you
+hold, served or on disk, is current when its size in bytes matches the manifest's; a file whose size
+differs is read online.
 
 What such a run does not produce: the Astro build and its release. Those need a machine with the
 CLI. Everything else the kit does to a site, it does through calls you can make, the frontend
@@ -75,32 +94,25 @@ Restaurants, Donations, FAQ), goes on with the Apps Installer:
 ## 4. The seed
 
 `seed-{solution}.mjs` is a sequence of REST calls, and `SEED.md` is its contract: the plan shape
-(what to create, how many, which images), the order the entities need, and the traps the script
-encodes (a Bookings service needs a category to be visible and takes resource ids, not staff ids;
-a Forms field is registered by its `validation` block; a product's choice photos are linked after
-the gallery holds them; right after a bulk create a product's own stock summary can still read
-`OUT_OF_STOCK` while its inventory items are already stocked, so check the items (Query Inventory
-Items) and create only the missing ones, as `SEED.md` says, where `ALREADY_EXISTS` means stocked; stock that isn't counted, such as "made to order", is
-`inStock: true`, never a missing quantity, which leaves the product unbuyable). Read `SEED.md`
-before the first create call: it maps the brief's words to the fields. Those fields are the
-script's input, not the request: the body each create sends is built in the script (for products,
-`bulkCreateProducts` in `seed-store.mjs`: the description as rich-text nodes from `mkDesc`,
-`productType` with `physicalProperties`, the stock as `inventoryItem`), so read that function before
-the first create. On a site this run created, the store's currency is `SEED.md`'s `currency` rule,
-the one the brief or the user's own pages state (a page priced "$68" is USD), set before the
-products and without asking; a confirmation before a currency change is for a store the user
-already runs. Then read the script for any call `SEED.md` only names, and make the same
-calls through `{MANAGE}`'s recipe for each (services, products, posts, events, collections). Keep
-the script's rules: create, never delete, and report what the site already held. A photo already in
-the site's Media Manager, such as one the user uploaded, goes in by its file id (`imageMediaId` in
-`SEED.md`), as it is: an import by URL would copy it. A photo on a site the user dropped is served
-with the drop, not from the Media Manager: it goes in by its live URL, imported once through
-`{MANAGE}/references/media/upload-media-to-wix.md`, and the file id the import returns is what the
-product or service takes. Image prompts need the Media Manager; without
-it, products and services stay text-only, say so. The scripts read
-a response body directly; `ExecuteWixAPI`'s `wix.request` returns `{ status, data }`, and the body
-is `data`. A generated image is billed when it is generated, so a read of the wrong level discards
-a paid image.
+(what to create, how many, which images), the order the entities need, the request bodies and the
+traps the script encodes. Read `SEED.md` before the first create: it maps the brief's words to the
+fields, and the script's builder functions turn those fields into each request, so the bodies you
+send are the ones they build. A call `SEED.md` only names is made through `{MANAGE}`'s recipe for
+it. Keep the script's rules: create, never delete, and report what the site already held. The closing
+names entities you drafted as placeholders.
+
+A photo already in the site's Media Manager, such as one the user uploaded, goes in by its file id
+(`imageMediaId` in `SEED.md`), as it is: an import by URL would copy it. A photo on a site the user
+dropped is served with the drop, not from the Media Manager: it goes in by its live URL, imported
+once through `{MANAGE}/references/media/upload-media-to-wix.md`, and the file id the import returns
+is what the entity takes. An `imagePrompt` is generated through
+`{MANAGE}/references/media/generate-image-with-ai.md` (`POST /runwareschemaless/v1/request`, the
+body `generateImage` in `{TEMPLATES}/shared/seed/images.mjs` builds), then imported through
+`upload-media-to-wix.md`, and the file id goes on the entity, as for a dropped photo; this is the
+seed's default for every entity that shows a picture. An entity stays text-only only when generation
+or the import fails; say which. The scripts read a response body directly; `ExecuteWixAPI`'s
+`wix.request` returns `{ status, data }`, and the body is `data`. A generated image is billed when
+it is generated, so a read of the wrong level discards a paid image.
 
 ## 5. The frontend
 
@@ -108,6 +120,9 @@ The run is not done until the pages use what the backend holds: every control th
 it (add to cart, the cart, book, submit) works on the live site. A backend with untouched pages is
 half a run.
 
+A payment (a cart, a paid booking, a ticket, a plan, a donation) ends in Wix's hosted checkout,
+reached through a redirect session, and is wired on the first pass, payments connected or not.
+
 The Astro pages cannot be released here: that is a run with a machine and a CLI login, which
 attaches to this site (`guides/existing-site.md`) rather than making a new one. What ships from here
 is static files, dropped onto the site from step 2 through
@@ -145,16 +160,14 @@ with `{TEMPLATES}/shared/app/wix/sdk.ts` for the client wiring): those files cal
 modules the page imports, and they are verified. Copy the form of the call, not the file. A page
 that talks to Wix over plain `fetch`, with no SDK, takes them from the REST twins instead:
 `{TEMPLATES}/shared/rest/client.ts` (the visitor token and the request) and
-`{TEMPLATES}/{solution}/rest/*.ts` (the calls; for a store, `storefront/rest/cart.ts` and
-`storefront/rest/catalog.ts`). Read those files by name; the manifest and the solution's whole
-`INSTRUCTIONS.md` are not needed to find them. The
-cores beside them (`*-core.ts`) hold the rules the page needs and nothing else does: which fields
-to read, how a price or a duration is formatted, which slot is bookable, how an id is read. Copy
-those core functions into the page as they are, with only the types removed (`cart-core.ts`'s
-`toLine` and `toCart`, the price formatter, `rawId`), and run every API response through them: a
-raw field read by hand is where a page breaks (a product name is a translatable object, a cart
-line's quantity is `quantityInfo.confirmedQuantity`). What you write is the markup, the rendering
-of what the cores return, and the event handlers.
+`{TEMPLATES}/{solution}/rest/*.ts` (the calls), each importing its helpers by their real paths.
+The cores,
+`{TEMPLATES}/{solution}/app/wix/{solution}/*-core.ts`, hold the rules the page needs and nothing else
+does: which fields to read, how a price or a duration is formatted, which slot is bookable, how an
+id is read. Copy those core functions into the page as they are, with only the types removed, and
+run every API response through them: a raw field read by hand is where a page breaks (a name can be
+a translatable object, a quantity a nested one). What you write is the markup, the rendering of what
+the cores return, and the event handlers.
 
 **A call those files don't cover** is confirmed before it is written, the way `{DOCS}` describes:
 the method's SDK page, and when the page and the package disagree, the package's own type
@@ -162,14 +175,31 @@ declarations (the `@wix/auto_sdk_{solution}_<module>` package the solution packa
 its `index.d.ts`) are the truth. Two shapes that recur, as examples of what the types settle and
 the kit's files already encode: SDK query methods return a query builder finished with `.find()`;
 and an entity's id arrives as `_id` on some objects and `id` on others (the kit reads both,
-`rawId`). Dates travel as local wall-clock strings in the business time zone. A page cannot be
-opened here, so a wrong shape fails silently in the browser. Check the data code before the upload:
-get a real response through `ExecuteWixAPI` for each call the page makes, run the page's data code
-on it in your sandbox's Node, and look for names, prices and quantities in the output, not
-`[object Object]` or `undefined`. The cart's calls run as a visitor, which `wix.request` (the
-owner) is not: in the script, mint a visitor token with the site's public client id as
-`shared/rest/client.ts` does (`POST https://www.wixapis.com/oauth2/token`, `grantType: "anonymous"`),
-send the cart calls with it through `fetch`, add one product and read the cart back.
+`rawId`). Dates travel as local wall-clock strings in the business time zone.
+
+**The check**, before every upload: a page cannot be opened here, so a wrong shape fails silently in
+the browser. In one `ExecuteWixAPI` script, make each control's calls the way the page makes them,
+as a visitor, with the bodies from `{solution}/rest/*.ts`. Then read the solution's cores,
+`{TEMPLATES}/{solution}/app/wix/{solution}/*-core.ts` (online, that folder's `_content` returns them
+in one response), and run each response through them in your sandbox's Node, as the page does:
+
+```js
+async function () {
+  const api = "https://www.wixapis.com", clientId = "<appId>";
+  const post = (path, body, token) => fetch(api + path, { method: "POST",
+    headers: { "Content-Type": "application/json", ...(token && { Authorization: token }) },
+    body: JSON.stringify(body) }).then(async (r) => ({ path, status: r.status, data: await r.json() }));
+  const { data: { access_token: token } } = await post("/oauth2/token", { clientId, grantType: "anonymous" });
+  const results = [];
+  // each call the control makes, in order: results.push(await post(path, body, token));
+  // a payment's last call is the redirect session the solution's rest/*.ts creates
+  return results;
+}
+```
+
+Done when every call returns 200, the cores turn each response into the names, prices, quantities or
+times the page shows, and a payment's redirect session returns a URL. The upload waits for that: a
+failing call is fixed first, on the site or in the page. The closing reports the check.
 
 ## 6. Closing
 

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

@@ -27,6 +27,12 @@ shape as setup (SKILL.md step 3):
 node <SKILL_ROOT>/install/attach.mjs --site <siteId> --business-name "<site name>" --vertical <vertical>[,<vertical>] [--plan plan.json]
 ```
 
+The same call takes a folder that already holds the site's config and the CLI's blank Astro
+starter with no work of its own (`context.mjs` says `blank-starter`: a Wix Dev Machine for a
+never-released site, or a bare `wix create`): `--site` comes from the config, the vertical's
+composed template takes the starter's place, its lockfile with it, and the install and the seed
+run detached as below. Do not install by hand there; the brand layer is yours while they run.
+
 `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

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

@@ -17,8 +17,9 @@ call is memory, and an empty or error reply to it says nothing about the site.
 
 ## Skills
 
-Installed at `.agents/skills/` (by the Wix plugin, or by
-`npx skills add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage`).
+Installed at `.agents/skills/` by
+`npx skills add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage`; a Wix plugin keeps
+its copy, under the same names, in the client's own skills folder.
 
 - `{{SKILL}}` — the code in this app and how to extend it. The shipped code is the
   `wix-headless-templates` skill: `node .agents/skills/{{SKILL}}/install/templates.mjs` prints where it

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

@@ -46,13 +46,16 @@
 // Emits ONE JSON event per line (attached, scaffolded, deployed, install_started,
 // ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@<pinned> whoami`, the version in pins.json)
 // whose account owns or co-manages the site.
-import { spawn, spawnSync, execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
+import { ignoreEnvLocal } from "./env-ignore.mjs";
 import { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
+import { failure, npmSync, startBackground } from "./proc.mjs";
+import { blankStarter } from "./context.mjs";
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
@@ -90,6 +93,10 @@ const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wi
 // config's site.outputDirectory names (a static site laid out for release) — install/context.mjs.
 const fp = frontendPresent(cwd);
 const hasProject = fp.packageJson || fp.rootIndex || fp.outputIndex;
+// The CLI's blank starter with no work of its own (a Dev Machine's never-released site, a bare
+// `wix create`): not a project to link, a scaffold to complete — the vertical's composed template
+// takes its place (deploy.mjs), the install and the seed run detached as for a new site.
+const starter = !!cwdConfig && fp.packageJson && !(fp.publicIndex && !fp.astroPages) && blankStarter(cwd);
 // 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).
@@ -122,24 +129,24 @@ if (hosting0 === "self" && stack === "astro" && !hasProject && !stackFlag) {
   fail("args", "--hosting self scaffolds nothing: pass --stack for the frontend you will host (react|lib|static), or attach from inside the project on disk");
 }
 if (!subfolder) {
-  if (hasProject && cwdConfig) {
-    fail("place", "this folder is already a Wix project with a frontend (wix.config.json and a project): nothing to attach. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install");
+  if (hasProject && cwdConfig && !starter) {
+    fail("place", "this folder is already a Wix project with a frontend (wix.config.json and a project): nothing to attach. deploy.mjs <vertical> adds this skill's code or a solution to it; then node <SKILL_ROOT>/install/install.mjs");
   }
   if (cwdConfig && (cwdConfig.siteId ?? cwdConfig.projectId) !== siteId) {
     fail("place", `this folder is attached to site ${cwdConfig.siteId ?? cwdConfig.projectId}, not ${siteId} — a folder is never re-pointed; attach the other site with --subfolder`);
   }
-  if (hasProject && !stackFlag) {
+  if (hasProject && !starter && !stackFlag) {
     fail("args", "attaching a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
   }
 }
-const mode = !subfolder && hasProject ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
-emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null, siteOrigin });
+const mode = !subfolder && hasProject && !starter ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
+emit("folder", { mode, stack, hosting: hosting0, project: hasProject, starter, config: cwdConfig ? "same site" : null, siteOrigin });
 
 // ---- http ---------------------------------------------------------------------------------------
 const cliToken = (site) => {
-  const r = spawnSync("npx", ["-y", WIX_CLI, "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
+  const r = npmSync("npx", ["-y", WIX_CLI, "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
   const t = (r.stdout || "").trim();
-  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || `no token — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-400));
+  if (r.status !== 0 || !t) fail("auth", failure(r, `no token — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-400));
   return t;
 };
 async function call(base, path, { method = "POST", token, site, body, query } = {}) {
@@ -163,6 +170,13 @@ async function call(base, path, { method = "POST", token, site, body, query } =
 }
 
 const folderName = flag("folder-name") ?? (businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "site");
+const renamePackage = (dir, name) => {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath)) return;
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.name = name;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+};
 const projectDir = subfolder ? resolve(cwd, folderName) : cwd;
 if (subfolder && existsSync(join(projectDir, "wix.config.json"))) fail("args", `${folderName}/ is already a Wix project — pick --folder-name, or run deploy.mjs there`);
 
@@ -277,13 +291,9 @@ if (stack === "astro" && mode === "scaffold") {
   // 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;
-  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-  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");
+  // The blank starter keeps its name through deploy, which recognizes it by name and gives it the
+  // composed package.json and lockfile; the project takes the folder's name after that (below).
+  if (!starter) renamePackage(projectDir, folderName);
 }
 writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify({ appId, siteId }, null, 2) + "\n");
 // The env the CLI's build reads. Same content `wix env pull` writes; written here so the build
@@ -297,6 +307,7 @@ writeFileSync(join(projectDir, ".env.local"), [
   `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
   "",
 ].join("\n"));
+ignoreEnvLocal(projectDir); // in every mode: a linked project's own .gitignore may not cover it
 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,20 +324,19 @@ if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
 let deployResult = {};
 {
   const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(planPath ? ["--plan", resolve(planPath)] : [])], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
-  if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
+  if (deploy.status !== 0) fail("deploy", failure(deploy));
   try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going */ }
   if (deployResult.error) fail("deploy", deployResult.error);
   emit("deployed", deployResult);
+  if (starter) renamePackage(projectDir, folderName);
 }
 
 // ---- 4 · dependency install, detached (any project with a package.json) --------------------------
 let install = null;
 if (existsSync(join(projectDir, "package.json"))) {
   const installLog = join(projectDir, "npm-install.log");
-  const logFd = openSync(installLog, "a");
-  const child = spawn("sh", ["-c", existsSync(join(projectDir, "package-lock.json")) ? "npm ci --ignore-scripts || npm install --ignore-scripts" : "npm install --ignore-scripts"], { cwd: projectDir, detached: true, stdio: ["ignore", logFd, logFd] });
-  child.unref();
-  install = { log: installLog, doneMarker: "node_modules/.package-lock.json" };
+  startBackground("install", [], { cwd: projectDir, log: installLog });
+  install = { log: installLog, doneMarker: ".install-exit", success: "file contains 0" };
   emit("install_started", install);
 }
 
@@ -339,12 +349,7 @@ if (planPath) {
   const seedDir = join(TEMPLATES, verticals[0], "seed");
   const seedName = existsSync(seedDir) ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs")) : undefined;
   if (!seedName) fail("seed", `no seed module found under ${seedDir}`);
-  const seedChild = spawn(
-    "sh",
-    ["-c", `node "${join(seedDir, seedName)}" "${resolve(planPath)}" > seed-result.json 2> seed.log; echo $? > .seed-exit`],
-    { cwd: projectDir, detached: true, stdio: "ignore" },
-  );
-  seedChild.unref();
+  startBackground("seed", [join(seedDir, seedName), resolve(planPath)], { cwd: projectDir });
   seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
   emit("seeding_started", { vertical: verticals[0], ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${verticals[0]}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
 } else {

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

@@ -0,0 +1,32 @@
+// The detached jobs setup.mjs and attach.mjs start (through proc.mjs startBackground), run by node
+// so they need no shell on any OS. Each leaves the files the caller syncs on:
+//
+//   node background.mjs install                install.mjs: nothing when node_modules already satisfies
+//                                              the lock, npm install when a tree is there, else npm ci
+//                                              (falling back to npm install); --ignore-scripts, output
+//                                              inherited (the install log); the exit code to .install-exit
+//   node background.mjs seed <seed.mjs> <plan>  the seed's stdout to seed-result.json, its stderr to
+//                                              seed.log, then its exit code to .seed-exit
+import { spawnSync } from "node:child_process";
+import { closeSync, openSync, writeFileSync } from "node:fs";
+import { runInstall } from "./install.mjs";
+
+const [job, ...args] = process.argv.slice(2);
+
+if (job === "install") {
+  const r = runInstall(process.cwd());
+  console.log(`install: ${r.decision}${r.lock ? ` (${r.lock.missing} of ${r.lock.total} lock entries were missing)` : ""}`);
+  process.exit(r.status);
+} else if (job === "seed") {
+  const [seedFile, plan] = args;
+  const out = openSync("seed-result.json", "w");
+  const err = openSync("seed.log", "w");
+  const r = spawnSync(process.execPath, [seedFile, plan], { stdio: ["ignore", out, err], windowsHide: true });
+  closeSync(out);
+  closeSync(err);
+  if (r.error) writeFileSync("seed.log", `the seed could not start: ${r.error.message}\n`, { flag: "a" });
+  writeFileSync(".seed-exit", `${r.status ?? 1}\n`);
+} else {
+  console.error("usage: background.mjs install <ci|install> | seed <seed.mjs> <plan.json>");
+  process.exit(2);
+}

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

@@ -2,7 +2,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
@@ -14,10 +14,17 @@ const fail = (event, extra = {}) => {
   process.exit(1);
 };
 
-// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
+// ── npx on every platform ────────────────────────────────────────────────────
+// On Windows npx is a .cmd shim, which Node starts only through a shell; a detached shell opens its
+// own console, and the login's JSON events never reach the log. npm ships npx's JS entry beside
+// node.exe, and that starts directly with node: no shell, no window, and the pid is the CLI's.
+// A Node without npm beside it (a version manager's shim) keeps the .cmd through the shell.
 const isWin = process.platform === 'win32';
-const bin = (name) => (isWin ? `${name}.cmd` : name);
-const WIX = [bin('npx'), '-y', WIX_CLI]; // run the CLI via npx — no global install/mutation
+const NPX_JS = isWin ? join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npx-cli.js') : null;
+const NPX = NPX_JS && existsSync(NPX_JS)
+  ? { file: process.execPath, pre: [NPX_JS], shell: false }
+  : { file: isWin ? 'npx.cmd' : 'npx', pre: [], shell: isWin };
+const WIX = [NPX.file, ...NPX.pre, '-y', WIX_CLI]; // run the CLI via npx — no global install/mutation
 
 // Force the CLI into non-interactive "agent" mode. Without an agent signal in
 // the env, `wix login` renders an interactive Ink TUI (device code + keypress)
@@ -36,17 +43,26 @@ const PIDFILE = join(STATE_DIR, 'login.pid');
 
 // run a command, capture stdout+stderr (combined), return {status, out}
 function capture(cmd, args, opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: NPX.shell, windowsHide: true, env: AGENT_ENV, ...opts });
   return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
 }
 
 // ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
+// A line holding only a version is the CLI's answer ("npm notice" lines carry versions too).
+const VERSION_LINE = /^\s*(\d+\.\d+\.\d+\S*)\s*$/m;
+const answered = (r) => r.status === 0 || VERSION_LINE.test(r.out);
+
 function checkCli() {
-  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
-  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
+  let r = capture(WIX[0], [...WIX.slice(1), '--version']);
+  // On a cold npm cache npx can exit non-zero after the version, the install's warnings around
+  // it; a second run finds the cache warm.
+  if (!answered(r)) r = capture(WIX[0], [...WIX.slice(1), '--version']);
+  if (!answered(r)) {
+    fail('cli_unreachable', { detail: (r.out.trim() || String(r.error?.message || `exit ${r.status}`)).slice(0, 400) });
+  }
   // npx interleaves "npm notice …" lines with the version, so don't just take the
-  // last line — pick the first semver-looking token, falling back to the last line.
-  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
+  // last line — pick the version line, else the first semver-looking token.
+  const version = r.out.match(VERSION_LINE)?.[1] || (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
   emit('cli_ok', { version });
 }
 
@@ -108,7 +124,8 @@ function startLogin() {
     detached: true,
     stdio: ['ignore', out, out],
     env: AGENT_ENV,
-    shell: isWin,
+    shell: NPX.shell,
+    windowsHide: true,
   });
   child.on('error', (e) => fail('login_failed', { detail: String(e) }));
   writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
@@ -127,7 +144,7 @@ async function waitForCode(timeoutMs = 60000) {
   }
   const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
   fail('login_failed', {
-    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
+    detail: detail || `wix login wrote nothing within ${timeoutMs / 1000}s; \`${['npx', '-y', WIX.at(-1), 'login'].join(' ')}\` run in the foreground prints the code.`,
   });
 }
 

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

@@ -13,12 +13,12 @@
 // 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 { basename, join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { SKILL_ROOT, TEMPLATES_PATH, 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 skillName = basename(SKILL_ROOT);
 const { repo } = installSource();
 
 const out = { skill: {}, templates: {}, update: {} };