@wix/agent-skills 1.31.0 → 1.31.2

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

@@ -1,10 +1,18 @@
 # The kit's run as Wix API calls
 
-Read when the commands this skill is built on cannot run where you are, or stopped: no shell, no
-file system, a sandbox that blocks the install, the CLI or the login, or a host that only talks to
-Wix through the Wix MCP. 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.
+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. 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
 
@@ -13,20 +21,40 @@ This skill is one of a set, and the guide reads from three of them:
 - `{SKILL_ROOT}` — this skill, `wix-headless-kit`: the run, its guides, the Verticals table.
 - `{TEMPLATES}` — `wix-headless-templates`: the shipped, verified code per Wix Business Solution,
   one folder each, with its `INSTRUCTIONS.md` (the contracts), `seed/` (the seed script and
-  `SEED.md`) and `rest/` (the data layer over plain `fetch`). Installed beside this skill, or
-  fetched to `{SKILL_ROOT}/templates/`.
+  `SEED.md`) and `rest/` (the data layer over plain `fetch`). Not every install carries it (a
+  plugin may leave it out): it is installed beside this skill, or fetched to
+  `{SKILL_ROOT}/templates/` by `node {SKILL_ROOT}/install/templates.mjs` (a git clone), or installed
+  with `npx skills@latest add wix/skills --skill wix-headless-templates`; with none of those, read
+  online at `https://www.wix.com/skills/wix-headless-templates/{path}`.
 - `{MANAGE}` — `wix-manage`: REST recipes to configure and manage a site's business solutions, one
   recipe per operation with the exact endpoint and payload; its `SKILL.md` is the index.
 - `{DOCS}` — `wix-docs`: how to look up the Wix API and SDK documentation and confirm a method's
   exact shape before writing a call.
 
-Installed, they sit beside each other under `.agents/skills/`. Online, they are published alongside
-each other under the same names, each with a manifest of its files, 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.
+Installed, they sit beside each other wherever your client keeps them: under `.agents/skills/` after
+`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.
+
+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.
+CLI. Everything else the kit does to a site, it does through calls you can make, the frontend
+included: step 5 ships it as static files.
 
 ## 0. Identity
 
@@ -42,6 +70,9 @@ Unchanged from SKILL.md step 2 and its Verticals table: the brief names the busi
 names the solutions it needs. Read each solution's `{TEMPLATES}/{solution}/INSTRUCTIONS.md` for
 what it covers and `{TEMPLATES}/{solution}/seed/SEED.md` for what a seeded site holds.
 
+A brief that needs no solution (a game, a landing page, a tool) is a run of two steps: the site
+(step 2, with no `seedOptions`) and the frontend (step 5). No apps, no seed.
+
 ## 2. The site
 
 The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
@@ -63,23 +94,45 @@ 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). Read `SEED.md`, 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. Image prompts
-need the Media Manager; without it, products and services stay text-only, say so.
+(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
 
+The run is not done until the pages use what the backend holds: every control the page shows for
+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
-`{MANAGE}/references/sites/upload-static-site.md`. Which files depends on whether the compose can
-run.
+`{MANAGE}/references/sites/upload-static-site.md`: the Wix MCP's upload tool, or a script that
+downloads what the site serves, edits it and drops it back, so only what changed is written. Which
+files depends on whether the compose can run, and on what writing them costs: when files reach the
+upload tool as files (its `attachments`), anything on your disk travels as it is; when they don't,
+every file you send is text you write, and the smallest set wins.
 
-**When the compose can run** (the skills on disk and Node), the frontend is the kit's own shipped code. The compose
+**When the compose can run** (the skills on disk, Node, and npm reachable, for the TypeScript compiler it fetches), the frontend is the kit's own shipped code. The compose
 `{SKILL_ROOT}/install/deploy.mjs {solution} --stack static --out site --client-id {appId}` fetches the
 templates and writes the solution's REST data layer and stores to `site/js/wix/` as plain ES modules
 (`guides/reference-mode.md`, the static site): the transport, the cores, the state machines, verified,
@@ -89,9 +142,11 @@ takes the complete file set in one call and a response has a hard size limit; th
 later" section downloads what the site serves, so a later drop adds files to a live set without
 resending what is already there.
 
-**When it cannot**, a page that loads the Wix SDK from a package CDN and talks to the site as a
-visitor. A few files at most, each written in full before it is dropped; the same size limit and
-the same way to add files to a live set apply. The
+**When it cannot**, or when its output would all have to be written out by hand, a page that loads
+the Wix SDK from a package CDN and talks to the site as a visitor. One file per call, a few hundred lines, written in full inside that call: a response has a
+hard size limit, and a call that carries the whole frontend at once exceeds it. A second file joins
+the first the recipe's way, "Change it later": the same call downloads the live set and drops the
+union. The
 SDK comes from a pinned package URL, `https://esm.sh/@wix/sdk@{version}` and the solution's package
 (`@wix/bookings`, `@wix/stores`, `@wix/blog`, …); the client is
 `createClient({ modules: { … }, auth: OAuthStrategy({ clientId }) })` with the `appId` the provision
@@ -102,9 +157,17 @@ holds; nothing invented, as in SKILL.md step 4.
 **The calls**, on that second path, take their shape from the kit's own transport for the solution,
 `{TEMPLATES}/{solution}/app/wix/{solution}/*.ts` (`services.ts`, `booking.ts`, `catalog.ts`, …,
 with `{TEMPLATES}/shared/app/wix/sdk.ts` for the client wiring): those files call the same SDK
-modules the page imports, and they are verified. Copy the form of the call, not the file. 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.
+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), 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
@@ -112,9 +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 run
-here, so a wrong shape fails silently in the browser; the file beside the skill is the check that is
-available.
+`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

@@ -7,7 +7,8 @@ is the create flow's job on a site made for the run — a folder holding only a
 is that case too: `init` made the site; SKILL.md step 3). (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").
+in the folder `node <SKILL_ROOT>/install/templates.mjs` prints (`<templates>` below; SKILL.md, "The
+model").
 
 **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:
@@ -26,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
@@ -46,7 +53,7 @@ for: what the chosen verticals will render, roughly how much of it, and what it
 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>]
+node <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

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

@@ -1,7 +1,9 @@
 # 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
+installed skill folder; the shipped code is in the folder `node <SKILL_ROOT>/install/templates.mjs`
+prints (the `wix-headless-templates` skill beside this one, or a copy fetched into
+`<SKILL_ROOT>/templates/`), and every `templates/…` path here is relative to it. 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
@@ -31,6 +33,12 @@ two transports: with `--plan` its REST twin and stores land in `js/wix/` beside
   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).
+- **A dropped site on its Wix Dev Machine** (shape `static-in-astro`). The machine holds the
+  dropped pages in `public/` of an Astro starter with no pages of its own, and its Astro config
+  redirects `/` to `/index.html`. The pages stay where they are: run
+  `deploy.mjs <vertical> --stack static --out public`, which writes `public/js/wix/`, and wire the
+  pages in place as above. The config is left as it is, so the release goes through Astro:
+  `npx @wix/cli@latest build && npx @wix/cli@latest release`, to the same URL.
 - **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

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

@@ -17,15 +17,18 @@ 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 sits in
+- `{{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
+  is (`.agents/skills/wix-headless-templates/` when installed beside this skill, else
   `.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
+  project at the commit it was built from, `templates/.source`) and fetches it when neither exists;
+  `<templates>` below is that folder. Each business solution has a playbook at
+  `<templates>/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
+  adds one; `node <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/`.

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 }));
@@ -304,7 +315,7 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
   emit("ready", { projectDir, siteId, appId, baseUrl, hosting, frontend, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
     next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack}${planPath ? ` --plan ${planPath}` : ""} (the client id is read from wix.config.json); ` +
-      (planPath ? `then seed with the plan: node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
+      (planPath ? `then seed with the plan: node ${join(TEMPLATES, verticals[0], "seed", `seed-${verticals[0]}.mjs`)} ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
       (hosting === "self" ? `; you host it: origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}` : "") });
   process.exit(0);
 }
@@ -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,20 +349,15 @@ 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 {
   if (siteOrigin === "init") {
-    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per templates/${verticals[0]}/seed/SEED.md — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
+    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per ${join(TEMPLATES, verticals[0], "seed", "SEED.md")} — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
   }
   if (verticals.includes("members")) {
-    emit("note", { step: "seed", detail: "members: the Members Area app (the profile layer, no content) is installed by templates/members/seed/seed-members.mjs — run it unless the site already has the app" });
+    emit("note", { step: "seed", detail: `members: the Members Area app (the profile layer, no content) is installed by ${join(TEMPLATES, "members", "seed", "seed-members.mjs")} — run it unless the site already has the app` });
   }
 }
 

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: {} };