@wix/agent-skills 1.31.1 → 1.32.0

package/skills/wix-base44-connector/SKILL.md

@@ -111,7 +111,7 @@ const wx = require(require("path").resolve(P));
 - `wx.bash(cmd)` — shell over saved files (GNU grep/sed; awk is mawk; no rg)
 - `wx.spec(docsUrl | code)` — a method's exact schema, plus the titles of the docs' own request examples saved at `examplesPath`; pass a hit's docsUrl (direct load), or raw code to query the index yourself
 - `wx.mgmtRecipes(q?)` — management-recipe index; no arg → categories, a word → matching recipes
-- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
+- `wx.ensureOAuthApp(token, { name, redirectUris, redirectDomains })` — the headless OAuth app, found by name or created with `origin: "base44-app"`, with the redirect lists merged into whatever it already allows; returns `{ clientId, created }`. `clientId` is what the browser mints visitor tokens from. Run it whenever `context` reports no OAuth app, or before any Wix-hosted flow that returns to this app — see Visitor authentication and Wix-hosted flows
 - `wx.installApp(appDefId, siteId, token)` — install a Wix app on the site (Apps Installer). If discovery finds an API whose app isn't installed on the site, install it first — that's a one-call prerequisite, **not** a reason to fall back to a hand-built alternative. `appDefId` from `search` or the Apps-Created-by-Wix table; `siteId` from `context` (the site report)
 
 Search makes one combined request across REST, management recipes, and Headless by default.
@@ -363,7 +363,9 @@ creating the OAuth app when the site has none and adding your URLs to its lists
 has one. Returns only complete for URLs in those lists, and a missing one breaks silently —
 create-checkout and the anonymous token still succeed — until a real buyer is redirected and
 stranded on Wix. It is idempotent by name: never create a second OAuth app for the same Base44
-app, or the first `clientId`'s returns stop working.
+app, or the first `clientId`'s returns stop working. The app is created with `origin: "base44-app"`,
+the name of this flow on the OAuth app; `origin` is set at creation only, so an OAuth app created
+by hand carries the same value in its create call.
 
 ```js
 // Register BOTH of this app's own URLs — its preview URL and its published URL — so returns work

package/skills/wix-base44-connector/scripts/utils.cjs

@@ -432,7 +432,10 @@ async function installApp(appDefId, siteId, token) {
 // return needs. Idempotent by name — a site reached by the "connect an existing site" flow
 // has none, and creating a second one for the same app strands the first app's returns.
 // Redirect lists are merged, never replaced: an app that already serves a custom domain
-// keeps it when a preview URL is added.
+// keeps it when a preview URL is added. `origin` names the flow that created the app; it is
+// written once, at creation, and an update leaves it as it is.
+const OAUTH_APP_ORIGIN = "base44-app";
+
 async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains = [] }) {
   const { oAuthApps = [] } = await post(
     "https://www.wixapis.com/oauth-app/v1/oauth-apps/query", { query: {} }, token);
@@ -440,7 +443,7 @@ async function ensureOAuthApp(token, { name, redirectUris = [], redirectDomains
   const merge = (a = [], b = []) => [...new Set([...a, ...b])];
   if (!existing) {
     const { oAuthApp } = await post("https://www.wixapis.com/oauth-app/v1/oauth-apps", {
-      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains },
+      oAuthApp: { name, allowedRedirectUris: redirectUris, allowedRedirectDomains: redirectDomains, origin: OAUTH_APP_ORIGIN },
     }, token);
     return { clientId: oAuthApp.id, created: true, oAuthApp };
   }

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
@@ -285,7 +294,10 @@ only after an explicit yes, never automatically. Step 5 ends with the same self-
    `https://manage.wix.com/dashboard/<siteId>` (the `siteId` of the `ready_for_brand_layer`
    event: on a migration preview that is the migrated site's dashboard, the release URL is the
    preview's, the original site is unchanged, and completing the migration is the user's next
-   step in the Wix CLI once they approve — say all three). When the site takes money through
+   step in the Wix CLI once they approve — say all three). Tell the user how to put their own
+   domain on the site, per the `wix-manage` recipe `references/domains/domain-search-purchase-and-connect.md`
+   (installed beside this skill, else `https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md`):
+   bought through Wix, or one they already own. When the site takes money through
    hosted checkout (a cart, a paid booking or rental, tickets, plans, donations) and nothing says
    payments are already set up, say what a visitor meets at checkout until they are — "We
    can't accept online payments. Contact us for help with your order." — and hand the two links

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
@@ -57,7 +76,7 @@ A brief that needs no solution (a game, a landing page, a tool) is a run of two
 ## 2. The site
 
 The CLI's `npm create @wix/new` is one call: `POST /headless-business-setup/v1/headless-business/provision`,
-with `origin: agent-<your-id>`, a name, and the solutions to install as `seedOptions`. The recipe
+with `origin: "drop"`, a name, and the solutions to install as `seedOptions`. The recipe
 is `{MANAGE}/references/sites/create-headless-site.md`; it returns the `metaSiteId` and the
 site's OAuth client `appId`. Do not create a site any other way: a project from Create Project or
 a template is neither headless nor publishable, and a later run with a machine cannot attach to it.
@@ -75,32 +94,26 @@ 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. Write the seed as your own `ExecuteWixAPI` script, its calls made on the
+new site: `wix.request({ scope: "site", siteId: <the metaSiteId>, … })`. Read `SEED.md` before
+the first create: it maps the brief's words to the fields. Build each request body in your script the
+way the script's builder functions do. 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 +121,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
@@ -127,49 +143,57 @@ 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**, 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
+**When it cannot**, or when its output would all have to be written out by hand, a page that talks
+to the site as a visitor over plain `fetch`. 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
-call returned, and the SDK mints and refreshes the visitor token itself. Markup, a render function
+page calls the Wix REST API with `fetch` and mints the visitor token itself with the `appId` the
+provision call returned, as `{TEMPLATES}/shared/rest/client.ts` does. Markup, a render function
 per state, the event handlers: that is what you write. Keep what the page shows to what the site
 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. A page
-that talks to Wix over plain `fetch`, with no SDK, takes them from the REST twins instead:
+**The calls**, on that second path, take their shape from the kit's REST twins for the solution:
 `{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.
+They are verified. Copy the form of the call, not the file.
+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
-declarations (the `@wix/auto_sdk_{solution}_<module>` package the solution package depends on,
-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.
+the method's REST page, and its schema (SearchWixAPISpec on the method's docs URL) for the exact
+request and response. A shape that recurs, as an example of what the kit's files already encode:
+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.
+
+**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);
+}