@wix/agent-skills 1.19.2 → 1.20.0

package/skills/wix-manage/references/seo/manage-seo-suggestions.md

@@ -0,0 +1,351 @@
+---
+name: "Generate AI SEO Suggestions for a Wix Site"
+description: "Generate AI-written SEO text for a Wix site through the public Tag Suggestions and Page Optimization APIs: title tag and meta description options for a page, alt text for the images of a page, store product, or blog post (one image or up to 20 per call), corrected heading levels for a page's headings, and a whole-page rewrite of title, description, headings, and body text aimed at the page's focus keyword, returned as before/after pairs. Use it when the user wants to improve, optimize, audit, or write the SEO text of a page or the homepage. Suggestions are returned for review; applying one is a separate SEO tags write."
+---
+
+# Generate AI SEO Suggestions for a Wix Site
+
+The **Tag Suggestions API** writes single texts from content you pass in: title
+tags, meta descriptions, image alt text, heading levels. The **Page Optimization
+API** reads a page from the Wix site itself and returns a whole-page rewrite as
+before/after pairs. Neither changes the site: every result is a suggestion for
+the user to review. Both select the site from the caller's authorization context
+and take no site ID. Use the site already selected in the environment. If none
+is selected, list the available sites. Select the only site automatically; if
+several are available, ask the user to choose by name before making
+site-specific calls. Never invent a site ID or ask the user to type one.
+
+All endpoints are under `https://www.wixapis.com/seo/suggestions/v1`. Reads of
+the site's pages and writes of its tags use the SEO Tags API under
+`https://www.wixapis.com/promote/seo/v1`. Every request and response shape a
+flow needs is in this recipe, verified against the live API: build the calls
+from here, including the two SEO Tags calls (List Item SEO Tags, and the
+focus-keyword write). Do not open the linked reference articles or search API
+schemas before calling; the links are for cases this recipe does not cover.
+
+| User asks for | Call |
+|---|---|
+| A better SEO title or meta description for a page | Generate Title Suggestions, Generate Description Suggestions |
+| Alt text for images of a page, product, or post | Generate Alt Text Suggestions (one) or Bulk Generate Alt Text Suggestions (up to 20) |
+| Check or fix a page's heading hierarchy | Generate Heading Structure Suggestions |
+| Optimize or rewrite a page for a keyword, "improve this page's SEO" | Trigger Page Optimization, or Trigger Home Page Optimization for the homepage, then poll Get Page Optimization Results |
+
+"Optimize", "rewrite", or "improve the SEO of" a page means the page
+optimization flow: it reads the page's real text and rewrites title,
+description, headings, and body together. The title and description generators
+are not a substitute for it; they know nothing about the page's content and
+cover two tags only. Use them when the user asks for title or description
+options, not when they ask to optimize a page.
+
+Each call spends AI generation and returns fresh text; nothing is stored except
+page optimization results. Suggestions come back in the site's language, and
+there is no parameter to change it.
+
+## Find the page first
+
+Every flow except title and description needs the page's ID, and most need to
+know what the page renders today. Read it once with
+[List Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags):
+
+```
+GET https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE?paging.limit=50
+```
+
+Relevant response fields (other tags omitted; IDs are illustrative):
+
+```json
+{ "itemSeoTags": [ { "itemId": "c1dmp", "itemType": "STATIC_PAGE",
+    "focusKeywords": [ { "term": "jewelry making styles", "isMain": true } ],
+    "resolvedTags": [
+      { "tag": { "type": "title", "children": "Home | Luna" }, "source": "TAG_SOURCE_DEFAULT_PATTERN" },
+      { "tag": { "type": "link", "props": { "rel": "canonical", "href": "https://www.example.com" } }, "source": "TAG_SOURCE_DEFAULT_PATTERN" },
+      { "tag": { "type": "meta", "props": { "name": "description", "content": "..." } }, "source": "TAG_SOURCE_ITEM" } ] } ],
+  "pagingMetadata": { "hasNext": false, "cursors": {} } }
+```
+
+- `itemId` is the page ID (`pageId` in every call below). Identify the page by
+  its resolved `title` tag; if that is ambiguous, ask the user which page.
+- The page path is the path of the canonical `link` `href`: `/cart-page` for
+  `https://www.example.com/cart-page`.
+- The homepage is the entry whose canonical `link` `href` equals the site URL,
+  ignoring a trailing slash; on a free site that URL includes a path. Compare
+  only canonicals with `source` `TAG_SOURCE_DEFAULT_PATTERN`. Its path is `/`.
+- `focusKeywords` with `isMain: true` is the focus keyword page optimization uses.
+- The current title and description are the `title` tag and the `meta` tag named
+  `description` in `resolvedTags`; pass them as context, never present them as
+  suggestions.
+- If `pagingMetadata.hasNext` is `true`, pass `pagingMetadata.cursors.next` as
+  `paging.cursor` on the next request until it is `false`.
+
+The SEO Tags API names a site page `STATIC_PAGE`; the suggestion APIs name the
+same page `STATIC_PAGE_V2`. Other item types are spelled the same in both:
+`STORES_PRODUCT`, `BLOG_POST`, `BOOKINGS_SERVICE`. Any other string returns
+`INVALID_ARGUMENT` with "expected itemType to be a seo supported item type".
+
+## Title and description suggestions
+
+Both take the content in the request, so they work for any page, including one
+the site does not have yet. Default `pageType` is `WEBSITE_PAGE`; use `HOMEPAGE`
+for the homepage, `PRODUCT_PAGE`, `PRODUCT_CATEGORY_PAGE`, `BLOG_POST`,
+`BLOG_CATEGORY_PAGE`, `SERVICE_BOOKING_PAGE`, `EVENT_PAGE`,
+`RESTAURANT_MENU_PAGE`, `PORTFOLIO_PROJECT_PAGE`, or `OTHER_APP_PAGE` as fits.
+`primaryKeyword` is the keyword the user wants the page to rank for; when the
+user named none, use the page's `isMain` focus keyword if it has one.
+
+[Generate Title Suggestions](https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/generate-title-suggestions),
+`pageName` required:
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/title
+```
+
+```json
+{ "pageType": "HOMEPAGE", "pageName": "Home", "primaryKeyword": "boutique hotel santorini" }
+```
+
+```json
+{ "tagSuggestions": { "suggestions": [ "Experience Boutique Hotel Santorini Luxury and Charm | Luna", "Discover Boutique Hotel Santorini: Unique Stays & Stunning Views | Luna" ] } }
+```
+
+[Generate Description Suggestions](https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/generate-description-suggestions),
+`pageName` and `topic` required; `primaryKeyword`, `toneOfVoice`,
+`businessType`, `businessLocation`, and `pageContent` (the page's text, up to
+100,000 characters) are optional hints that may or may not appear in the text:
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/description
+```
+
+```json
+{ "pageType": "HOMEPAGE", "pageName": "Home", "topic": "Boutique hotel in Santorini",
+  "primaryKeyword": "boutique hotel santorini", "toneOfVoice": "warm" }
+```
+
+The response has the same `tagSuggestions.suggestions` shape. Both return best
+match first, up to 10, often fewer: texts outside the target length or missing
+the keyword are filtered out. Titles aim for 45 to 65 characters, descriptions
+for 130 to 165. Send page content only in the free-text fields, never personal
+data: they are sent to the AI model and written to service logs.
+
+Applying a text is a separate write that needs the user's approval. Read the
+page's current tags with
+`GET https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE/{pageId}`,
+merge the new `{ "type": "title", "children": "..." }` or
+`{ "type": "meta", "props": { "name": "description", "content": "..." } }` into
+the full `tags` array it returns, and send the whole array back with
+`PATCH https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE/{pageId}`
+and body `{ "itemSeoTags": { "tags": [ ... ] }, "fieldMask": "tags" }`. The
+write replaces the page's tags in full, so a body holding only the new tag
+deletes every other tag the page had. Static pages save to the draft unless the
+body also has `"publish": true`. Full rules:
+[Set Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/set-item-seo-tags).
+
+## Alt text suggestions
+
+Alt text is generated only for images that belong to a Wix item, identified by
+the item's ID and type; the item's stored SEO data gives the AI its context.
+The image URL must be on a Wix media domain (`static.wixstatic.com` or another
+`wixstatic.com` / `wixmp.com` host). Any other host fails the whole call with
+`INVALID_ARGUMENT` on `image.url`: "Alt text can only be generated for
+Wix-hosted images". Do not retry with the same URL.
+
+For a store product, get the ID and image URLs from Query Products
+(`POST https://www.wixapis.com/stores/v3/products/query` with
+`{ "query": { "cursorPaging": { "limit": 20 } }, "fields": ["MEDIA_ITEMS_INFO"] }`):
+each product's `id` is the `parentItemId`, and `media.itemsInfo.items[].image.url`
+are its image URLs. For a site page, `parentItemId` is the page's `itemId` from
+List Item SEO Tags (listed there under `STATIC_PAGE`), and the alt-text call's
+`itemType` is `STATIC_PAGE_V2`.
+
+[Generate Alt Text Suggestions](https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/generate-alt-text-suggestions),
+one image; `id` is your own label, echoed back:
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/alt-text
+```
+
+```json
+{ "itemType": "STORES_PRODUCT",
+  "image": { "id": "main", "url": "https://static.wixstatic.com/media/22e53e_5a34c410f18f4760b451208652e8cf27~mv2.jpg",
+             "parentItemId": "7ef5f127-5e5d-4ebb-9957-d122ce56daec" } }
+```
+
+```json
+{ "altTextSuggestions": { "imageId": "main", "url": "https://static.wixstatic.com/media/22e53e_5a34c410f18f4760b451208652e8cf27~mv2.jpg",
+    "suggestions": [ "Ceramic flower vase with dried roses on a stone surface" ] } }
+```
+
+[Bulk Generate Alt Text Suggestions](https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/bulk-generate-alt-text-suggestions),
+up to 20 images of the same `itemType` per call; split larger sets:
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/alt-text-bulk
+```
+
+```json
+{ "itemType": "STORES_PRODUCT", "images": [
+    { "id": "main", "url": "https://static.wixstatic.com/media/22e53e_5a34c410f18f4760b451208652e8cf27~mv2.jpg", "parentItemId": "7ef5f127-5e5d-4ebb-9957-d122ce56daec" },
+    { "id": "second", "url": "https://static.wixstatic.com/media/22e53e_0a3fe4969636459b8fde2bde4bbe109d~mv2.jpg", "parentItemId": "7ef5f127-5e5d-4ebb-9957-d122ce56daec" } ] }
+```
+
+```json
+{ "results": [ { "imageId": "main", "success": true, "suggestions": [ "Dried roses in a matte ceramic flower vase on a stone ledge." ] },
+               { "imageId": "second", "success": true, "suggestions": [ "Minimalist matte beige ceramic flower vase" ] } ],
+  "successCount": 2, "failureCount": 0 }
+```
+
+`results` follow request order. An entry with `success: false` has no
+suggestions: retry that image alone with the single-image call, once. Up to 5
+suggestions per image, often one. Report `failureCount` as returned. Applying
+alt text happens in the product's or page's own settings, not through these APIs.
+
+## Heading structure suggestions
+
+[Generate Heading Structure Suggestions](https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/generate-heading-structure-suggestions)
+takes the page's headings in page order, each with its raw HTML and your own
+`id`; `sectionId` groups headings that belong to one section. It must be called
+with a Wix user identity (a signed-in site owner or an app acting for one);
+with an API key the call fails, by design, because the page title is read
+through the site's accessibility analysis, which runs as the user.
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/heading-structure
+```
+
+```json
+{ "pageId": "c1dmp", "itemType": "STATIC_PAGE_V2",
+  "headings": [ { "id": "hero", "htmlString": "<h1>Luna Boutique Hotel</h1>", "sectionId": "hero" },
+                { "id": "rooms", "htmlString": "<h3>Our rooms</h3>", "sectionId": "rooms" },
+                { "id": "rooms-suite", "htmlString": "<h4>Caldera suite</h4>", "sectionId": "rooms" },
+                { "id": "contact", "htmlString": "<h1>Contact us</h1>", "sectionId": "contact" } ] }
+```
+
+```json
+{ "suggestions": [ { "headingId": "rooms", "currentTag": "H3", "proposedTag": "H2" },
+                   { "headingId": "rooms-suite", "currentTag": "H4", "proposedTag": "H3" },
+                   { "headingId": "contact", "currentTag": "H1", "proposedTag": "H2" } ] }
+```
+
+Only headings that should change are returned; an empty `suggestions` array
+means the structure is already correct. `proposedTag` `P` means the text should
+not be a heading. Up to 200 headings per call. The heading text comes from the
+user or from the page content you already have; this recipe has no method that
+fetches a page's headings.
+
+## Page optimization: trigger, then poll
+
+Page optimization reads the page from the site's latest saved revision, so
+unpublished edits count and the site need not be published. It needs two
+things, checked in this order:
+
+1. **A Wix-rendered site.** Headless projects fail with `FAILED_PRECONDITION`,
+   code `SITE_NOT_SUPPORTED`. Stop and tell the user: nothing else in this
+   section can work on that site.
+2. **A focus keyword on the page** (`focusKeywords` entry with `isMain: true`
+   from List Item SEO Tags). Without one the trigger fails with
+   `FAILED_PRECONDITION`, code `FOCUS_KEYWORD_NOT_SET`. If the user named the
+   keyword they want the page to rank for, set it, then trigger; if they did
+   not, ask for it. The focus keyword is the input the job needs, not one of the
+   suggested changes: a user who says "optimize my page for X but don't apply
+   anything yet" still expects X to be set as the focus keyword, and only the
+   returned before/after texts to be held back. Setting it is a write to the
+   page's SEO settings:
+
+   ```
+   PATCH https://www.wixapis.com/promote/seo/v1/item-seo-tags/STATIC_PAGE/{pageId}
+   ```
+
+   ```json
+   { "itemSeoTags": { "focusKeywords": [ { "term": "handmade ceramic mugs", "isMain": true } ] }, "fieldMask": "focusKeywords" }
+   ```
+
+   The field mask limits the write to `focusKeywords`, so the page's tags are
+   untouched and no read is needed before this write: List Item SEO Tags already
+   returned the page's current `focusKeywords`, and the SEO Tags API's
+   read-before-write rule exists for the `tags` array, which this call does not
+   send. The response echoes the page with its new `focusKeywords`.
+
+Then start one job. Use
+[Trigger Home Page Optimization](https://dev.wix.com/docs/api-reference/business-management/seo/page-optimization-v1/trigger-home-page-optimization)
+for the homepage (its text represents the whole site, so it gets its own
+guidance) and
+[Trigger Page Optimization](https://dev.wix.com/docs/api-reference/business-management/seo/page-optimization-v1/trigger-page-optimization)
+for any other page. Both need a Wix user identity, like heading structure;
+both take the page ID and its path:
+
+```
+POST https://www.wixapis.com/seo/suggestions/v1/page-optimization/trigger-home
+```
+
+```json
+{ "pageId": "c1dmp", "pagePath": "/" }
+```
+
+```json
+{ "predictionId": "2247d724-1440-483d-bf66-f7edf8582a34" }
+```
+
+Keep `predictionId`. Triggering the same page again while its job runs returns
+the same `predictionId`, so a duplicate call is harmless, but do not send one on
+purpose: each trigger is counted against the daily cap below. Then poll
+[Get Page Optimization Results](https://dev.wix.com/docs/api-reference/business-management/seo/page-optimization-v1/get-page-optimization-results)
+every few seconds until `status` leaves `IN_PROGRESS`; generation usually
+finishes within two minutes:
+
+```
+GET https://www.wixapis.com/seo/suggestions/v1/page-optimization/results?predictionId=2247d724-1440-483d-bf66-f7edf8582a34
+```
+
+```json
+{ "status": "IN_PROGRESS" }
+```
+
+```json
+{ "pageOptimization": {
+    "metaTitle": { "before": "Home | Luna", "after": "Jewelry Making Styles by Luna in New York City | Online" },
+    "metaDescription": { "before": "", "after": "Explore jewelry making styles from Luna in New York City – shop our online store today." },
+    "h1": { "before": "Luna & Loop", "after": "Artisanal Jewelry Making Styles by Luna & Loop" },
+    "h2OrH3": { "before": "Luna & Loop Jewelry", "after": "Luna & Loop Jewelry Making Styles" },
+    "content": [] },
+  "status": "COMPLETED" }
+```
+
+- `COMPLETED`: present each pair as the current text and the proposed text. An
+  empty `before` means the page has no text in that slot yet (here, no meta
+  description). `content` lists body-text rewrites and can be empty.
+- `FAILED`: the job failed; trigger once more, and if it fails again report it.
+- `NOT_FOUND`: no job matches. The `predictionId` expires two hours after the
+  trigger, and a later trigger for the same page replaces the earlier job.
+  `GET .../page-optimization/results?pageId=c1dmp` returns the page's latest
+  completed set at any time, so use it when the user comes back later.
+- Applying a pair is the user's decision. Title and description go through Set
+  Item SEO Tags as described above; headings and body text are edited in the
+  page itself, which these APIs cannot do.
+
+## Limits and errors
+
+- Per-second limits: 5 requests per second per user for tag suggestions, 2 for
+  page optimization. A call rejected for rate limiting can be retried once after
+  a short pause.
+- Per-user daily caps on `www.wixapis.com`: 200 title, 200 description, 500
+  alt-text, 100 bulk alt-text, and 50 page-optimization triggers per day. A `429`
+  means the cap for that method is spent: stop calling it and tell the user it
+  resets the next day. Do not switch to another method to get the same text.
+- `403` or `PERMISSION_DENIED`: stop after the first one and report that the
+  current identity lacks the SEO permission (reads and generators need view
+  access to SEO settings, triggers and tag writes need manage access). Do not
+  try another site, path, method, or request shape: the same identity gets the
+  same answer.
+- Heading structure or a trigger failing with an internal error or `403` under
+  an API key is the identity rule above, not an outage: say a Wix user identity
+  is required and stop.
+- `FAILED_PRECONDITION`: read `details.applicationError.code`.
+  `FOCUS_KEYWORD_NOT_SET` and `SITE_NOT_SUPPORTED` are covered above;
+  `CONTENT_TOO_SHORT` means the page has too little text to optimize, so the user
+  must add content first; `SUGGESTIONS_ALREADY_IN_PROGRESS` means a job with a
+  different focus keyword is still running, so poll that page by `pageId` and
+  trigger again when it completes. None of these succeeds on retry.
+- `GENERATION_FAILED` (`500`): the AI pipeline failed for this call; retry once,
+  then report.
+- `INVALID_ARGUMENT` (`400`): fix the field named in `fieldViolations` and send
+  once more; never cycle through guessed shapes.

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 });
+```