@wix/agent-skills 1.19.1 → 1.20.0

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -1,53 +1,283 @@
 ---
 name: "Upload a Website or HTML Files"
-description: Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+description: Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a new live Wix site. Covers both ways to get there — handing the user the Wix Headless drop page, and calling the Wix Headless instant-site REST API yourself when you can reach the files and make outbound HTTPS requests. When you also hold the user's identity, covers putting the published site straight into their Wix account and reading back its final live URL. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site already published this way (iterate on the same site instead of creating another). Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
 ---
 
 # Upload a Website or HTML Files
 
-The user already has a finished website as files — hand-written HTML, a zip
-export, or the output of an AI site builder — and wants it live on Wix as a
-new site. There is no API call to make. Send them to the upload page and
-explain the flow:
+The user has a finished website as files — hand-written HTML, a static build, a
+zip, or the output of an AI site builder — and wants it live on Wix as a new
+site. There are two ways to get there.
 
+## The two paths
+
+**[Path A — hand the user the drop page](#path-a--hand-the-user-the-drop-page).**
+One URL; the user uploads in the browser and gets a live site. This works for
+**any** agent and any user — it's the default. Reach for it whenever you can't
+clearly do Path B.
+
+**[Path B — publish the files yourself](#path-b--publish-the-files-yourself).**
+Three calls put the site live without the user touching a browser. Available only
+when **both** hold: you can read the file bytes (you generated them here, or
+they're reachable from where you run), **and** you can do a `multipart/form-data`
+file upload from a shell (`curl` or equivalent). Reaching APIs *only* through the
+Wix API-call/execute-API tools does **not** count — they can't upload a local
+file.
+
+Prefer Path B when you can genuinely do it — the user gets a live site without
+uploading anything themselves. Otherwise, and by default, take Path A. Decide
+honestly: if you can't read the bytes or can't upload from a shell, hand over the
+drop page rather than attempting Path B and reporting an upload you couldn't
+perform.
+
+## Path A — hand the user the drop page
+
+Send the user here:
+
+```
+https://www.wix.com/headless/drop?utm_campaign=mcp&agent=<your-agent-id>
+```
+
+**Keep `utm_campaign=mcp`** (the drop-flow referral tag — don't change it) **and set
+`agent` to your own identifier** — the coding agent or tool you are (e.g.
+`claude-code`, `cursor`, `codex-cli`, `windsurf`, `github-copilot`, or your product's
+name). Hand the URL with `agent` filled in and both params intact. There the user drags
+in their files (no login), Wix hosts them immediately on a live URL, and a banner
+offers to sign in and keep the site. Tell them the requirements from
+[What the upload accepts](#what-the-upload-accepts-and-how-it-fails) so it doesn't
+fail on the first try.
+
+## Path B — publish the files yourself
+
+> **Run every call from your shell with `curl` — not the Wix API-call/execute-API
+> tools.** The upload (step 2) and the download in
+> [Add a backend](#keep-building-add-a-backend-when-you-need-one) move a **file**
+> to or from disk; those tools proxy JSON and can't (hand-building a multipart
+> body inline silently drops every image and font). Create and release are plain
+> JSON and would work through anything, but the upload needs a real file client
+> anyway, so keep it all in the shell. **None of steps 1–3 (or the download) need
+> auth — they're anonymous.** Only [claim](#4-put-the-site-in-the-users-account)
+> needs the user's identity.
+
+```
+Base URL: https://www.wixapis.com/headless-business-setup
+```
+
+Generate `anonymousId` yourself — any UUID, **once per site, not once per
+request** — and reuse it (with the returned `metaSiteId`) for every call for that
+site, including later changes ([Iterate](#iterate-while-anonymous-dont-create-a-new-site)).
+**Finish within one hour of step 1**: after that the record expires and every
+later step, claim included, returns `404`.
+
+### 1. Create the site
+
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID"
+```
+
+```json
+{ "metaSiteId": "f0ad8672-09e9-4111-b6fe-070c70bd2df5",
+  "projectId":  "54528d34-b23c-4fbe-b07d-2c522350abd7" }
+```
+
+Keep both: `metaSiteId` addresses the site in every later call; `projectId`
+builds the save link in step 3b.
+
+### 2. Upload the files
+
+One `multipart/form-data` request carrying every file. Each file is a part named
+`files` whose **filename is its path relative to the site root** — that is how
+subdirectories survive; with `curl`, set it explicitly with `;filename=` whenever
+it isn't just the basename. A single `.zip` part works too — send it alone and
+it's unpacked server-side, a single wrapping folder stripped.
+
+```bash
+AGENT=claude-code   # ← replace with your own identifier (see note below)
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/upload?campaign=mcp&agent=$AGENT" \
+  -F "files=@index.html;filename=index.html" \
+  -F "files=@assets/styles.css;filename=assets/styles.css" \
+  -F "files=@assets/logo.png;filename=assets/logo.png"
+```
+
+```json
+{ "uploadId": "03244542-d820-42f6-acfa-166c6658b1a6" }
+```
+
+Keep `campaign=mcp` (the drop-flow referral tag — don't change it) and set
+`agent=$AGENT` to **your own identifier**: the coding agent or tool performing this
+drop, so the upload is attributed to the real client. Use a short, stable,
+lowercase-hyphenated slug — e.g. `claude-code`, `cursor`, `codex-cli`, `windsurf`,
+`github-copilot`, or your product's name; if you genuinely can't name yourself, use
+`unknown-agent`. Send the **same** `agent` on every upload for this site, matching
+the `agent` you'd use in Path A. Nothing is live yet; this only stages and validates.
+
+### 3. Release — the site goes live
+
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/release" \
+  -H 'Content-Type: application/json' \
+  -d "{\"uploadId\":\"$UPLOAD_ID\"}"
 ```
-https://www.wix.com/headless/drop?utm_campaign=mcp
+
+```json
+{ "siteUrl": "https://instant-hguwrvtcrniw-headlessstack-140d.wix-site-host.com" }
 ```
 
-**Always give the URL exactly as written above, including the
-`utm_campaign=mcp` query parameter.** It attributes the visit to an
-assistant/MCP referral; dropping or rewriting it breaks that attribution.
+The site is live at `siteUrl` immediately.
+
+#### Iterate while anonymous (don't create a new site)
+
+Simple static changes — new copy, another page, a different look — happen here,
+**while the site is still anonymous**, and this is the only window for them:
+re-run steps 2–3 with the **same `anonymousId` and `metaSiteId`**; the upload
+replaces the site's contents and `siteUrl` stays the same. Send the full file set
+each time (release replaces, it doesn't merge). Don't go back to step 1 — a fresh
+site per change leaves the user a trail of abandoned sites on changing URLs; only
+create another for a genuinely separate site.
+
+So **iterate first, claim last**: refine on the same ids until the site is right,
+*then* finish. Once claimed, these anonymous endpoints stop working and the only
+way to keep changing the site in code is a headless project
+([Keep building](#keep-building-add-a-backend-when-you-need-one)).
+
+**When the site is final, finish based on identity:**
+
+- **You have the user's access token** — claim it into their account (step 4).
+  Don't stop at a temporary site: an unclaimed site expires, so saving it is part
+  of publishing, not an extra favour to ask about.
+- **You have no user identity** — stop here; this is a finished, legitimate result
+  (exactly what the drop page produces for every visitor). Give the user `siteUrl`
+  plus the save link, which is how the site survives:
+
+  ```
+  https://www.wix.com/live-headless-site/{projectId}?anonymousId={anonymousId}
+  ```
 
-## What happens on that page
+  That page shows the site with a countdown and signs the user in to keep it.
+  Treat the link as a secret — whoever opens it while signed in to Wix claims the
+  site into *their* account — so give it only to the user who asked.
 
-1. The user drags in their files (or a zip) — no login needed.
-2. Wix hosts them immediately on a live URL they can open and share.
+### 4. Put the site in the user's account
 
-## Tell the user before they upload
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/claim" \
+  -H "Authorization: Bearer $ACCESS_TOKEN"
+```
+
+Returns `{}` on success; needs a user or account-level identity (else
+`UNAUTHENTICATED`). It consumes the anonymous record, so it's the last call that
+works against these endpoints — do it after the release, never before.
+
+**The site's URL changes here.** The step-3 host stops resolving — the free host
+is scoped to the owning account and re-minted under the user's. Read the new one
+in step 5; never repeat the step-3 URL after a claim.
+
+### 5. Read the site's final URL
+
+[Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites)
+filtered to the **`HEADLESS` namespace** — headless sites are omitted from the
+default query, so the filter is required, and an `id` filter is rejected, so match
+the id yourself.
+
+```bash
+curl -sS -X POST "https://www.wixapis.com/site-list/v2/sites/query" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"query":{"filter":{"namespace":"HEADLESS"},"cursorPaging":{"limit":100}}}'
+```
+
+Find the entry whose `id` equals your `metaSiteId`, read `viewUrl` (page with
+`metadata.cursors.next` if needed):
+
+```json
+{ "id": "f0ad8672-09e9-4111-b6fe-070c70bd2df5",
+  "displayName": "Snake", "published": true, "namespace": "HEADLESS",
+  "viewUrl": "https://instant-hguwrvtcrniw-ayalg5-1406.wix-site-host.com/" }
+```
+
+Give the user two links: `viewUrl` for the live site, and its dashboard at
+`https://manage.wix.com/dashboard/{metaSiteId}` to manage it.
+
+### What the upload accepts, and how it fails
+
+The requirements below apply to both paths — an upload that breaks them is why a
+release never happens:
+
+- **A top-level HTML file is required.** It needn't be named `index.html` (a lone
+  top-level HTML of any name becomes the homepage), but once there's more than
+  one, an `index.html` must be among them.
+- **3 MB per file, 20 MB per site.**
+- **Static files only** — HTML, CSS, JS, images, fonts. Framework source that
+  needs a build step (a `package.json`, React/Vue sources) must be built first;
+  upload the build output.
+
+On Path B, failures come back as HTTP 400 with a code in
+`details.applicationError.code`: `MISSING_INDEX_HTML` (add a top-level HTML),
+`FILE_TOO_LARGE` (a file over 3 MB), `TOTAL_TOO_LARGE` (bundle over 20 MB). A
+`404` after step 1 means the one-hour window passed or the site was already
+claimed — start again from step 1.
+
+**If Path B fails for any reason you can't quickly fix — a rejected upload, an
+error, a call you can't make — fall back to [Path A](#path-a--hand-the-user-the-drop-page):
+give the user the drop-page link so they can finish in the browser.** Never leave
+them with a failed publish and no way forward; the drop page reaches the same
+result without the step that broke.
+
+## Keep building: add a backend when you need one
+
+The drop flow publishes **static** files. When the site needs a real backend —
+stores, payments, bookings, a CMS, members, forms — it becomes a **Wix Headless
+project**. This is a solution the user chooses when the need appears, not a
+required step: a static site is a finished result on its own.
+
+Offer it once the site is claimed/owned and you're in a coding environment with a
+shell. It keeps the **same site, appId and URL** (the downloaded project already
+carries a `wix.config.json` binding it), and is released with the Wix CLI from
+then on:
+
+```bash
+curl -sSL -o project.zip \
+  "https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/$META_SITE_ID/download.zip"
+unzip project.zip -d project      # index.html + assets + wix.config.json
+```
 
-Share the requirements that match their situation — these are the common
-reasons an upload fails:
+Then follow `https://wix.com/headless/skill.md`: it turns the static files into a
+headless project (`@wix/sdk` + the business solutions the site needs), bound to
+the same site.
 
-- The upload must contain an **HTML file at the top level of the site's
-  files**. It does not need to be named `index.html` — a single HTML file of
-  any name is served as the homepage — and a zip or folder that wraps
-  everything in one top-level folder (e.g. `my-site/index.html`) is unwrapped
-  automatically.
-- Size limits: **3 MB per file, 20 MB total.**
-- **Static files only** — HTML, CSS, JavaScript, and assets. If the user has
-  framework source code that needs a build step (a `package.json`, React/Vue
-  source, etc.), they must run their build first and upload the build output
-  folder's contents, not the source.
+This is the only way to keep changing a **claimed** site in code, and it's why it
+needs `wix login`: re-releasing to a claimed site is authenticated *and*
+file-based, and an authenticated file operation needs the token in your **shell**
+(via `wix login`), not injected into a tool — the API-call/execute-API tools carry
+the auth but can't do file operations. There's no lighter "re-upload static to my
+claimed site" shortcut.
 
 ## Route the request correctly
 
-| The user has… | Do this |
-|---|---|
-| Site files on their machine (HTML/zip/AI-builder export), wants a new site | This recipe — send them to the drop URL above |
-| A live site or store on another platform (a URL), or CSV/TSV exports, and wants content/products migrated | [Site Import](site-import.md) |
-| An existing Wix site they want to add HTML, an embed, or custom code into | Not this recipe — that's embedding custom code in the site editor |
-| Images, videos, or documents to add to a site | [Upload Media to Wix](../media/upload-media-to-wix.md) — media goes to the site's media files, not a new site |
+- **You can't read the files, can't make HTTP calls, or have no shell
+  (API-call/execute-API tools only, which can't upload a file)** — Path A, the
+  drop page. It's also the default whenever Path B isn't clearly available, and
+  the fallback whenever Path B fails partway — hand over the link, don't leave the
+  user stuck.
+- **Files you generated here or can read, and you can upload from a shell** —
+  Path B. If you hold the user's identity, claim it into their account and return
+  the live URL + dashboard.
+- **A change to a site you published this way here** —
+  [iterate in place](#iterate-while-anonymous-dont-create-a-new-site) on the same ids.
+- **A published anonymous site the user wants to keep** — steps 4–5 with their
+  identity, else the step-3 save link.
+- **A claimed site that now needs a backend** (stores, bookings, CMS, members,
+  forms) — [add a backend](#keep-building-add-a-backend-when-you-need-one).
+- **Migrating a live site/store from another platform by URL, or CSV/TSV
+  exports** — [Site Import](site-import.md).
+- **Adding HTML, an embed, or code to an existing Wix site** — not this recipe
+  (that's custom code in the editor).
+- **Images, videos, or documents for a site** —
+  [Upload Media to Wix](../media/upload-media-to-wix.md).
 
-Do not try to perform the upload for the user through an API, and do not
-create a site for them with other site-creation tools instead — the drop page
-is the flow.
+Don't create the site with other tools (meta-site templates, headless-business
+provisioning) — those make an empty site, not a published copy of the user's files.

package/skills/wix-vibe-headless/install/deploy.cjs

@@ -15,10 +15,11 @@
 // No vertical arg -> deploys just the shared transport; re-run with the vertical(s) once known.
 // NOTE: .cjs on purpose — the app is an ESM package ("type":"module"); a .js here would load as ESM
 // and require()/module.exports would throw.
-const { existsSync, cpSync, readFileSync, writeFileSync } = require('fs');
+const { existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
 
 const REF = '/app/.agents/skills/wix-vibe-headless/references';
 const WIX_CONFIG = '/app/src/rest/wix-config.js';
+const NAV_ADAPTER = '/app/src/lib/nav.js';
 const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'forms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
 
 // force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
@@ -69,6 +70,32 @@ function replaceMembersAuthLeftovers() {
   return result;
 }
 
+// --- nav adapter --------------------------------------------------------------------------------
+//
+// Every shipped component imports Link/useParams/etc from "@/lib/nav", so one set of sources runs on
+// either Base44 template and the router is named in exactly one file. Which adapter belongs there is
+// a filesystem fact, so resolve it here rather than leaving the agent to infer the template and
+// hand-write the file: the react-router one is a re-export a model can guess, but the TanStack one
+// normalises useParams (strict:false) and useNavigate (object arg), and a guess breaks every page.
+//
+// The react-router adapter ships INSIDE shared/app/ (-> src/lib/nav.js), so it lands on every
+// install path, including hosts that copy that tree themselves and never run this script. Only the
+// TanStack override needs writing, and it goes down BEFORE the shared copy — that copy is
+// force:false, so whatever is at the path first wins.
+function detectTemplate() {
+  return existsSync('/app/src/routes/__root.jsx') ? 'tanstack' : 'react-router';
+}
+
+function installNavAdapter(template) {
+  if (template !== 'tanstack') return 'from_shared_tree';
+  const src = `${REF}/_shared/nav/nav.tanstack.js`;
+  if (!existsSync(src)) return 'adapter_missing_from_skill';
+  if (existsSync(NAV_ADAPTER)) return 'already_present';   // same don't-clobber contract as COPY
+  mkdirSync('/app/src/lib', { recursive: true });
+  cpSync(src, NAV_ADAPTER);
+  return 'written';
+}
+
 // --- WRITE the credentials ----------------------------------------------------------------------
 //
 // The two ids arrive as flags so this script writes them once, character-for-character, instead of a
@@ -128,7 +155,11 @@ const deployed = { verticals: [] };
 const aliased = [...new Set(positional.filter((a) => ALIASES[a]))].map((a) => `${a} -> ${ALIASES[a]}`);
 if (aliased.length) deployed.aliased = aliased;
 
-// Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/).
+// Nav adapter — before the shared copy, which carries the react-router default at the same path.
+deployed.template = detectTemplate();
+deployed.navAdapter = installNavAdapter(deployed.template);
+
+// Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/, lib/nav.js).
 if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);
 
 // Each named vertical — its app/ (UI + app/rest/ helpers) -> src/.

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed-with-install.md

@@ -22,7 +22,7 @@ Install three skills — they land under `.agents/skills/`:
 - **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
 
 
-Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
+Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/` (the nav adapter at `src/lib/nav.js` among them), and pins the AGENTS.md note. **Its `deploy` result reports this app's `template`** — `react-router` wires routes into `src/App.jsx`, `tanstack` mounts them as files under `src/routes/`; see [`../references/_shared/routing.md`](../references/_shared/routing.md).
 
 ```js
 const { execSync } = require('child_process');

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -18,11 +18,20 @@ These skills are already installed under `.agents/skills/`:
 - **`wix-manage`** — REST recipes for managing and configuring the Wix site.
 - **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
 
-Base44 has also deployed the storefront hooks, cart components/context, image helpers, and REST
-scaffolds into `src/`, configured the Wix connector/client, and added the Wix note to `AGENTS.md`.
-No installation, deployment, or AGENTS.md update is needed.
+Base44 has also deployed the storefront hooks, cart components/context, image helpers, REST
+scaffolds and the nav adapter (`src/lib/nav.js`) into `src/`, configured the Wix connector/client,
+and added the Wix note to `AGENTS.md`. No installation, deployment, or AGENTS.md update is needed.
+
 The deployed implementation and configuration files do not need to be read; use the build and seed
-guides below for their contracts and usage. Continue with STEP 1.
+guides below for their contracts and usage.
+
+**Mount pages the way this app's template expects** — ask `src/routes/__root.jsx` first: present →
+TanStack Start, where pages mount as route files and the deployed `src/lib/nav.js` needs swapping
+for `_shared/nav/nav.tanstack.js`; absent → React Router, routes wired into `src/App.jsx`. Building for the wrong one
+renders a blank preview with no error to explain it:
+[`../references/_shared/routing.md`](../references/_shared/routing.md).
+
+Continue with STEP 1.
 
 Follow STEPs 1–3 below exactly. Fire product image generations first, then build the client
 (STEP 1), and seed (STEP 2) **after** the client is built — generation finishes while you build.

package/skills/wix-vibe-headless/platforms/base44-ecom-light.md

@@ -21,7 +21,7 @@ Install three skills — they land under `.agents/skills/`:
 - **`wix-base44-connector`** — Wix connector usage, API contracts, and documentation discovery.
 
 
-Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/`, and pins the AGENTS.md note.
+Run this through exec_tool, exactly as written — installs all three skills, deploys the `storefront` REST scaffolds + UI into `src/` (the nav adapter at `src/lib/nav.js` among them), and pins the AGENTS.md note. **Its `deploy` result reports this app's `template`** — `react-router` wires routes into `src/App.jsx`, `tanstack` mounts them as files under `src/routes/`; see [`../references/_shared/routing.md`](../references/_shared/routing.md).
 
 ```js
 const { execSync } = require('child_process');

package/skills/wix-vibe-headless/platforms/base44.md

@@ -18,7 +18,7 @@ STEP 3, and **except a seed that attaches entity images**, which runs after the
 
 Install three skills under `.agents/skills/`: **`wix-vibe-headless`** (the client build + seed guide — your main source of truth), **`wix-manage`** (REST recipes to manage/configure the site), and **`wix-base44-connector`** (site context + API-doc discovery).
 
-Run this through exec_tool, exactly as written — installs all three skills, deploys REST scaffolds + UI into `src/`, writes `wix-config.js`, and pins the AGENTS.md note.
+Run this through exec_tool, exactly as written — installs all three skills, deploys REST scaffolds + UI into `src/` (the nav adapter at `src/lib/nav.js` among them), writes `wix-config.js`, and pins the AGENTS.md note. **Its `deploy` result reports this app's `template`** (`react-router` or `tanstack`) — STEP 3 needs it.
 
 **Set `VERTICALS`** to what the prompt asks for — **list every vertical the app uses**, since several often join the main one (too vague to tell? do STEP 2 first, then set it). Adding one later: re-run with the extra name.
 
@@ -91,9 +91,24 @@ truth for how the client is built.
 file the seed writes. Read its `INSTRUCTIONS.md` **Prerequisites** before building any form UI; seed
 it first (STEP 4) and build the rest of the app meanwhile.
 
-**`src/App.jsx`: edit surgically, never rewrite.** It carries required platform auth scaffolding
-(`AuthProvider`/`useAuth` from `@/lib/AuthContext`); a full rewrite drops them → the validator
-rejects the write. Wire routes/imports in with `find_replace`, leave the rest as-is.
+**Mount pages the way this app's template expects.** Base44 ships more than one and they route
+differently; building for the wrong one renders a blank preview with no error to explain it. STEP 1
+resolved which it is and reported it as `template`:
+
+- `tanstack` → **TanStack Start**: file-based routes under `src/routes/`, no `src/App.jsx`, no
+  `index.html`, build output in `.output/` rather than `dist/`. Pages mount as route files; chrome
+  and providers live in `__root.jsx`.
+- `react-router` → **React Router**: routes and providers are wired into `src/App.jsx`.
+
+Read the app's own `AGENTS.md` first either way — both templates ship one and it states their
+conventions. The mounting pattern for each, and what STEP 1 put in `src/lib/nav.js`:
+[`../references/_shared/routing.md`](../references/_shared/routing.md).
+
+**On the React Router template, `src/App.jsx` is edited surgically, never rewritten.** It carries
+required platform auth scaffolding (`AuthProvider`/`useAuth` from `@/lib/AuthContext`); a full
+rewrite drops them → the validator rejects the write. Wire routes/imports in with `find_replace`,
+leave the rest as-is. TanStack keeps the same scaffolding in `src/routes/__root.jsx` and
+`src/lib/AuthContext.jsx`, under the same rule: add around it, never replace it.
 
 ## STEP 4 — Manage and seed the business
 

package/skills/wix-vibe-headless/platforms/generic.md

@@ -17,6 +17,12 @@ Everything is under `.agents/skills/wix-vibe-headless/references/`.
 | `wix-client.js` | The transport: exchanges `WIX_CLIENT_ID` for an anonymous **visitor token**, persists + refreshes it (that token *is* the cart/session identity), and exposes `wixApiRequest(path, {method, body, query})` — plus the member-session swap (`setSessionTokens` / `clearSession` / `isMember`). Plain `fetch`; SSR-guards `window`/`localStorage`; maps 402 + error bodies. |
 | `wix-config.js` | Holds `WIX_CLIENT_ID` + `WIX_METASITE_ID` — the only values to fill in. |
 
+**Plus `shared/app/lib/nav.js`.** The reference UI imports `Link`, `useParams`, `useNavigate`,
+`useLocation` and `Navigate` from `@/lib/nav` rather than from a router, so one set of sources runs
+on any of them. Point that path at your own router's equivalents — the shipped file re-exports
+react-router's, and `_shared/nav/nav.tanstack.js` shows the kind of wrapping another router needs
+(params scoped to the current match, a `navigate` you call with a path).
+
 **Every `references/<vertical>/` holds the same four things:**
 
 - `app/rest/wix-*.js` — the vertical's **data layer**: named calls carrying the exact request/response

package/skills/wix-vibe-headless/references/_shared/nav/nav.tanstack.js

@@ -0,0 +1,30 @@
+// Navigation adapter — TanStack Start template (src/routes/ file-based routing).
+// Copy to src/lib/nav.js. Shipped components import Link/useParams/etc from here so the same
+// files run on either Base44 template; this file is the only place the router is named.
+//
+// Two shapes differ from react-router and are normalised here:
+//   useParams  — TanStack scopes params to a route; `strict: false` returns the current match's
+//                params, which is what a shared component wants.
+//   useNavigate — TanStack takes an object; this returns a function you call with a path, and
+//                 `navigate(-1)` still goes back.
+import {
+  Link as RouterLink,
+  Navigate,
+  useLocation,
+  useNavigate as useRouterNavigate,
+  useParams as useRouterParams,
+} from "@tanstack/react-router";
+
+// `to` is an already-resolved path (`/blog/my-post`); the router matches it at runtime.
+export const Link = RouterLink;
+export { Navigate, useLocation };
+
+export function useParams() {
+  return useRouterParams({ strict: false });
+}
+
+export function useNavigate() {
+  const navigate = useRouterNavigate();
+  return (to, options) =>
+    typeof to === "number" ? window.history.go(to) : navigate({ to, ...options });
+}

package/skills/wix-vibe-headless/references/_shared/routing.md

@@ -0,0 +1,86 @@
+# Mounting pages: which template is this app?
+
+Base44 ships more than one app template, and they route differently — so which one you are on
+decides how a page gets mounted. A page mounted the other template's way renders nothing, and the
+preview comes back blank with no error to explain it.
+
+**An install that ran `deploy.cjs` already told you** — its result carries the template it resolved
+from disk, as `{ "template": "react-router" }` or `{ "template": "tanstack" }`. Where the host
+deployed the tree itself there is no such line, and the same fact reads straight off the app —
+**ask `src/routes/__root.jsx` first**: present → TanStack Start (file-based routes, build output in
+`.output/` rather than `dist/`); absent → React Router SPA, routed from `src/App.jsx` with an
+`index.html` beside it. That order matters, because an `src/App.jsx` on a TanStack app is
+something an agent wrote believing the app was React Router — `__root.jsx` is never there by
+mistake. The app's own `AGENTS.md` (both templates ship one) states its conventions — worth a read
+before the first write.
+
+## On TanStack, four things differ from the React Router form
+
+Routing guidance you meet elsewhere — routes wired into `src/App.jsx`, `react-router-dom` imports,
+its `AuthProvider` / `QueryClientProvider` wrappers — describes the React Router template. On this
+one:
+
+- **There is no `src/App.jsx`, and that is the finished state.** Leave it absent; creating one
+  wires a router the app does not use, and the pages mounted in it never render.
+- **Route files import `createFileRoute` and `Link` from `@tanstack/react-router`**, which this
+  template installs.
+- **The wrappers live in `src/routes/__root.jsx`.** Same rule as `App.jsx` carries on the other
+  template: add around them, never replace them.
+- **Telling the two apart costs nothing** — the app's files are already in your context.
+
+## The nav adapter is already installed
+
+Shipped components import `Link`, `useParams` and friends from `@/lib/nav`, never from a router
+package, so one set of sources runs on either template. `src/lib/nav.js` arrives with the rest of
+the deployed tree, and it is the one place the router is named. Write your own pages against
+`@/lib/nav` too and they stay portable for free.
+
+**On TanStack, check what landed.** The deployed default is the React Router adapter, and
+`deploy.cjs` swaps the TanStack one in when it runs — but a host that copies the tree itself lands
+the default whatever the template. So on a TanStack app, open `src/lib/nav.js` and, if it
+re-exports from `react-router-dom`, copy `_shared/nav/nav.tanstack.js` over it. That file carries
+the two normalisations the imports depend on: `useParams` scoped with `strict: false`, and
+`useNavigate` returning a function you call with a path (`navigate(-1)` included).
+
+## React Router template
+
+One `Layout` holding your chrome renders `<Outlet/>`; every route nests under a single pathless
+route so the chrome wraps all pages. Each vertical's `STEP 3` carries the exact snippet, including
+where the preview banner sits.
+
+## TanStack Start template
+
+Same structure, expressed as files. The chrome that lives in `Layout` goes in `src/routes/__root.jsx`
+(it already renders the document and providers — add your header/footer around its `<Outlet/>`),
+and each route is its own file exporting `createFileRoute`:
+
+```jsx
+// src/routes/shop.jsx      →  /shop
+import { createFileRoute } from "@tanstack/react-router";
+import Shop from "@/pages/Shop";                      // the shipped page, unchanged
+
+export const Route = createFileRoute("/shop")({ component: Shop });
+```
+
+```jsx
+// src/routes/product.$slug.jsx   →  /product/:slug
+import { createFileRoute } from "@tanstack/react-router";
+import ProductDetail from "@/pages/ProductDetail";    // shipped; reads its param via @/lib/nav
+
+export const Route = createFileRoute("/product/$slug")({ component: ProductDetail });
+```
+
+Three things to carry over from the React Router wiring:
+
+- **Shipped pages stay where they are** (`src/pages/…`) and stay unedited. A route file is a
+  two-line mount, not a copy of the page.
+- **Path params use `$name`**, so `/product/:slug` becomes the file `product.$slug.jsx` and the
+  route path `/product/$slug`. `useParams()` from `@/lib/nav` returns them the same way.
+- **Providers** a vertical asks you to wrap the tree in (`CartProvider`, `MemberProvider`, …) go in
+  `__root.jsx` around `<Outlet/>`, once — not per route file.
+
+Per-user routes should also set `ssr: false` so personal data never lands in cacheable HTML:
+
+```jsx
+export const Route = createFileRoute("/my-plans")({ component: MyPlans, ssr: false });
+```