@wix/agent-skills 1.15.1 → 1.16.1

package/skills/wix-replatform/scripts/orchestration-state.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+  nowIso,
+  randomId,
+  orchestrationDir,
+  loadArtifacts,
+  initArtifacts,
+  validateArtifacts,
+  writeJsonAtomic,
+  appendEvent,
+  updateDecisionObject,
+  updateApprovalObject,
+  updateCheckpointObject,
+  transitionRun,
+} = require('../lib/orchestration-state.js');
+const { createProgressLogger, parseProgressArgs } = require('../lib/progress-log.js');
+
+let progress;
+
+function usage() {
+  console.log(`Usage:
+  node scripts/orchestration-state.js init --project-dir <dir> [--project-id <id>]
+  node scripts/orchestration-state.js validate --project-dir <dir>
+  node scripts/orchestration-state.js status --project-dir <dir>
+  node scripts/orchestration-state.js decide --project-dir <dir> --key <decisionKey> --value <jsonOrString> [--source user|deterministic_inference|prior_artifact] [--rationale <text>]
+  node scripts/orchestration-state.js approve --project-dir <dir> --type mapping|execution --status pending|approved|rejected|provisional [--notes <text>] [--decided-by user|system]
+  node scripts/orchestration-state.js checkpoint --project-dir <dir> --phase discovery|mapping|setup|codegen|execution --patch <json>
+  node scripts/orchestration-state.js transition --project-dir <dir> --state <state> --phase <activePhase> [--status <runStatus>] [--needs-user-input true|false] [--needs-llm true|false] [--resume-from <jsonReasonRef>]
+`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+    const key = token.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    args[key] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function parseMaybeJson(value) {
+  if (value == null) {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function parseBoolean(value, fallback) {
+  if (value == null) {
+    return fallback;
+  }
+  return String(value) === 'true';
+}
+
+async function saveArtifacts(projectDir, artifacts) {
+  const dir = orchestrationDir(projectDir);
+  await writeJsonAtomic(path.join(dir, 'run.json'), artifacts.run);
+  await writeJsonAtomic(path.join(dir, 'checkpoints.json'), artifacts.checkpoints);
+  await writeJsonAtomic(path.join(dir, 'decisions.json'), artifacts.decisions);
+  await writeJsonAtomic(path.join(dir, 'approvals.json'), artifacts.approvals);
+  if (artifacts.preflight) {
+    await writeJsonAtomic(path.join(dir, 'preflight.json'), artifacts.preflight);
+  }
+}
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  progress = createProgressLogger({
+    script: 'skills/replatform/scripts/orchestration-state.js',
+    ...parsed.progress,
+  });
+  progress.start('Orchestration state command started', { phase: 'orchestration' });
+
+  const args = parseArgs(parsed.args);
+  const command = args._[0];
+  if (!command || command === 'help') {
+    usage();
+    if (command) {
+      progress.complete('Orchestration state help shown', { phase: 'orchestration', step: 'help' });
+    } else {
+      progress.error('Missing orchestration state command', { phase: 'orchestration' });
+    }
+    process.exit(command ? 0 : 1);
+  }
+
+  if (!args.projectDir) {
+    throw new Error('--project-dir is required');
+  }
+  const projectDir = path.resolve(args.projectDir);
+
+  if (command === 'init') {
+    const artifacts = await initArtifacts(projectDir, { projectId: args.projectId || path.basename(projectDir) });
+    console.log(JSON.stringify({ ok: true, projectDir, state: artifacts.run.currentState }, null, 2));
+    progress.complete('Orchestration artifacts initialized', { phase: 'orchestration', step: 'init', artifact: projectDir });
+    return;
+  }
+
+  const artifacts = await loadArtifacts(projectDir);
+  if (!artifacts.run) {
+    throw new Error(`orchestration artifacts not initialized under ${projectDir}`);
+  }
+
+  if (command === 'validate') {
+    const result = validateArtifacts(artifacts);
+    console.log(JSON.stringify(result, null, 2));
+    if (result.ok) {
+      progress.complete('Orchestration artifacts validated', { phase: 'orchestration', step: 'validate', artifact: projectDir });
+    } else {
+      progress.error('Orchestration artifact validation failed', { phase: 'orchestration', step: 'validate', artifact: projectDir, count: result.errors.length, unit: 'errors' });
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  if (command === 'status') {
+    const result = validateArtifacts(artifacts);
+    console.log(JSON.stringify({
+      ok: result.ok,
+      currentState: artifacts.run.currentState,
+      activePhase: artifacts.run.activePhase,
+      runStatus: artifacts.run.status,
+      approvals: artifacts.approvals,
+      checkpointStatus: {
+        discovery: artifacts.checkpoints.discovery.status,
+        mapping: artifacts.checkpoints.mapping.status,
+        setup: artifacts.checkpoints.setup.status,
+        codegen: artifacts.checkpoints.codegen.status,
+        execution: artifacts.checkpoints.execution.status,
+      },
+      errors: result.errors,
+    }, null, 2));
+    if (result.ok) {
+      progress.complete('Orchestration status read', { phase: 'orchestration', step: 'status', artifact: projectDir });
+    } else {
+      progress.error('Orchestration status is invalid', { phase: 'orchestration', step: 'status', artifact: projectDir, count: result.errors.length, unit: 'errors' });
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  if (command === 'decide') {
+    if (!args.key || args.value == null) {
+      throw new Error('decide requires --key and --value');
+    }
+    updateDecisionObject(artifacts.decisions, args.key, parseMaybeJson(args.value), {
+      source: args.source || 'user',
+      rationale: args.rationale || null,
+      timestamp: nowIso(),
+    });
+    await saveArtifacts(projectDir, artifacts);
+    await appendEvent(projectDir, {
+      id: randomId('evt'),
+      timestamp: nowIso(),
+      phase: artifacts.run.activePhase,
+      state: artifacts.run.currentState,
+      type: 'decision.recorded',
+      payload: { key: args.key },
+    });
+    console.log(JSON.stringify({ ok: true, decision: args.key }, null, 2));
+    progress.complete('Orchestration decision recorded', { phase: 'orchestration', step: 'decide', entity: args.key, artifact: projectDir });
+    return;
+  }
+
+  if (command === 'approve') {
+    if (!args.type || !args.status) {
+      throw new Error('approve requires --type and --status');
+    }
+    updateApprovalObject(artifacts.approvals, args.type, args.status, {
+      notes: args.notes || null,
+      decidedBy: args.decidedBy || 'user',
+      timestamp: nowIso(),
+    });
+    await saveArtifacts(projectDir, artifacts);
+    await appendEvent(projectDir, {
+      id: randomId('evt'),
+      timestamp: nowIso(),
+      phase: artifacts.run.activePhase,
+      state: artifacts.run.currentState,
+      type: 'approval.updated',
+      payload: { approvalType: args.type, status: args.status },
+    });
+    console.log(JSON.stringify({ ok: true, approvalType: args.type, status: args.status }, null, 2));
+    progress.complete('Orchestration approval updated', { phase: 'orchestration', step: 'approve', entity: args.type, artifact: projectDir });
+    return;
+  }
+
+  if (command === 'checkpoint') {
+    if (!args.phase || !args.patch) {
+      throw new Error('checkpoint requires --phase and --patch');
+    }
+    updateCheckpointObject(artifacts.checkpoints, args.phase, parseMaybeJson(args.patch), nowIso());
+    await saveArtifacts(projectDir, artifacts);
+    console.log(JSON.stringify({ ok: true, phase: args.phase }, null, 2));
+    progress.complete('Orchestration checkpoint updated', { phase: 'orchestration', step: 'checkpoint', entity: args.phase, artifact: projectDir });
+    return;
+  }
+
+  if (command === 'transition') {
+    if (!args.state || !args.phase) {
+      throw new Error('transition requires --state and --phase');
+    }
+    artifacts.run = transitionRun(artifacts.run, {
+      state: args.state,
+      activePhase: args.phase,
+      status: args.status || artifacts.run.status,
+      needsUserInput: parseBoolean(args.needsUserInput, artifacts.run.needsUserInput),
+      needsLlm: parseBoolean(args.needsLlm, artifacts.run.needsLlm),
+      resumeFrom: args.resumeFrom ? parseMaybeJson(args.resumeFrom) : artifacts.run.resumeFrom,
+      timestamp: nowIso(),
+    });
+    await saveArtifacts(projectDir, artifacts);
+    await appendEvent(projectDir, {
+      id: randomId('evt'),
+      timestamp: nowIso(),
+      phase: artifacts.run.activePhase,
+      state: artifacts.run.currentState,
+      type: 'state.transitioned',
+      payload: { activePhase: artifacts.run.activePhase, runStatus: artifacts.run.status },
+    });
+    console.log(JSON.stringify({ ok: true, state: artifacts.run.currentState, phase: artifacts.run.activePhase }, null, 2));
+    progress.complete('Orchestration state transitioned', { phase: 'orchestration', step: 'transition', entity: args.state, artifact: projectDir });
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  if (progress) {
+    progress.error(error && error.message ? error.message : 'Orchestration state command failed', { phase: 'orchestration' });
+  }
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+});

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

@@ -39,7 +39,7 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
 - **Auth = one public client id.** `WIX_CLIENT_ID` is a **buyer/visitor-facing** credential —
   it only mints anonymous visitor tokens. It is **not a secret**; hardcoding and committing it
   is fine. The user provides it (their vibe/host platform surfaces a copyable prompt with the
-  id filled in). Paste it into `wix-client.js` in place of the `<YOUR-CLIENT-ID>` placeholder.
+  id filled in). Paste it into `wix-config.js` in place of the `<YOUR-CLIENT-ID>` placeholder.
 - **Money/price fields are objects, never scalars.** Every price/amount a Wix API returns —
   Stores `price.actualPrice`, Bookings service `payment.fixed.price`, Events ticket
   `registration.tickets.lowestPrice`, and the rest — has the shape `{ value, currency,
@@ -93,14 +93,16 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
 
 ## How this skill is structured
 
-`<SKILL_ROOT>` is this file's directory (strip `/SKILL.md`). Two files make up each vertical's
-runtime:
+`<SKILL_ROOT>` is this file's directory (strip `/SKILL.md`). Each vertical ships a **complete UI
+client as files** under `references/<vertical>/app/` — `components/`, `pages/`,
+`hooks/`/`context/`, and its REST helpers in `app/rest/` — plus the **shared transport** in
+`references/shared/app/` (`app/rest/wix-client.js` + `wix-config.js`, identical for every vertical).
+Set `WIX_CLIENT_ID` (and `WIX_METASITE_ID`) in `wix-config.js`. Deploying `references/<vertical>/app/`
+and `references/shared/app/` into the app's `src/` puts every file in place — the helpers all land in
+`src/rest/`, so their relative imports resolve.
 
-1. **The shared transport** — `references/shared/wix-client.js`. **Identical for every vertical.**
-   Copy it once into the app's `src/rest/` and set `WIX_CLIENT_ID` in it.
-2. **The vertical helper** — `references/<vertical>/<helper>.js`. Copy it into the **same**
-   `src/rest/` folder (it does `import { wixApiRequest } from "./wix-client.js"`, so the two
-   files must sit side by side).
+**Where these files live in the app, and how they get there** (pre-installed at setup, or copied
+in) **is your platform's call — follow your platform instructions for that.**
 
 Each vertical's `INSTRUCTIONS.md` is the full playbook for that solution: when to use it,
 prerequisites, the exported API, how to wire it, the hard rules, and a verification checklist.
@@ -111,28 +113,50 @@ prerequisites, the exported API, how to wire it, the hard rules, and a verificat
 Load the vertical(s) the user's app needs; a project may combine several (e.g. a restaurant
 with a blog, or a store with pricing plans).
 
-| The user wants… | Vertical | Read | Helper(s) to copy (+ `shared/wix-client.js`) |
-|---|---|---|---|
-| Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` | `wix-store-catalog.js` + `wix-store-cart.js` |
-| Appointments: services, time slots, booking, checkout | **bookings** | `references/bookings/INSTRUCTIONS.md` | `wix-bookings-services.js` + `wix-bookings-checkout.js` |
-| Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` | `references/blog/wix-blog.js` |
-| Events: browse, event page, RSVP, ticketing | **events** | `references/events/INSTRUCTIONS.md` | `wix-events-browse.js` (always) + `wix-events-registration.js` (RSVP/tickets) |
-| Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` | `references/portfolio/wix-portfolio.js` |
-| Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` | `wix-restaurants-menu.js` (always) + `wix-restaurants-ordering.js` + `wix-restaurants-reservations.js` as needed |
-| CMS content: list/detail, filter/search, forms, data CRUD | **cms** | `references/cms/INSTRUCTIONS.md` | `references/cms/wix-cms.js` |
-| Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` | `references/pricing-plans/wix-pricing-plans.js` |
-| Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` | `references/members/wix-members-auth.js` |
+Each vertical's UI + helpers ship in `references/<vertical>/app/`; copy that dir plus
+`references/shared/app/` into the app's `src/` (base44 does this at install via `deploy.cjs`).
+
+| The user wants… | Vertical | Read |
+|---|---|---|
+| Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` |
+| Appointments: services, time slots, booking, checkout | **bookings** | `references/bookings/INSTRUCTIONS.md` |
+| Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` |
+| Events: browse, event page, RSVP, ticketing | **events** | `references/events/INSTRUCTIONS.md` |
+| Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` |
+| Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` |
+| CMS content: list/detail, filter/search, forms, data CRUD | **cms** | `references/cms/INSTRUCTIONS.md` |
+| Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
+| Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` |
+
+### When the request doesn't name a Wix Business Solution — ask, or check the site
+
+Don't infer which Wix Business Solution to build (stores, bookings, blog, events, portfolio,
+restaurants, CMS, pricing plans, members, etc..) from a vague brief. **Ask the user** one short
+question — what do they offer (products? appointments? posts? events?) — or **check what the
+site actually has**: call a cheap read from each likely solution's helper (`queryProducts`,
+`queryServices`, `queryPosts`, `queryEvents`, …) — authenticated with a visitor token minted
+from the `WIX_CLIENT_ID`, or with an admin token if you have one — and build for the solutions
+that return real content. A `428` "app not installed" (blog: `401`) means
+that solution isn't on the site; sample-looking content ("Sample product 3") proves the app is
+installed, not what the business is about. Never default to store/bookings on silence.
 
 ## The run
 
 1. **Get `WIX_CLIENT_ID`.** It comes from the user (the handoff prompt from their Wix/vibe
    platform carries it). If it's missing, ask for it before wiring — nothing works without it.
-2. **Pick the vertical(s)** from the routing table and open each one's `INSTRUCTIONS.md`.
-3. **Copy the two files per vertical** — `shared/wix-client.js` (once) + the vertical helper —
-   into the app's `src/rest/` (adjust only the import path if the app uses a different folder),
-   and set `WIX_CLIENT_ID`.
-4. **Wire the UI** to the exported helpers following the vertical's INSTRUCTIONS. Build the UI
-   however the project wants — these scaffolds ship the REST layer only, no components.
+2. **Pick the vertical(s)** from the routing table — and when the request doesn't name any,
+   **ask or check the site** (see above) instead of guessing. Open each picked vertical's
+   `INSTRUCTIONS.md`.
+3. **Ensure the vertical's files are in place** — copy `references/<vertical>/app/` and
+   `references/shared/app/` into the app's `src/`, and set `WIX_CLIENT_ID` in `wix-config.js`. (Where
+   and how they get there is your platform's call — see its instructions. On base44 the install step
+   writes and verifies `wix-config.js` for you, so there's nothing to set by hand.)
+4. **Wire the shipped client** following the vertical's INSTRUCTIONS: the components are themed by
+   base44's design tokens (`src/index.css` — shadcn palette, already set by the design phase), so
+   there's no re-skin step; just wire routes + header/footer through the Layout. The UI ships as
+   files — you compose the home page and wire it, you don't rebuild the client. Style what you add
+   from the same tokens: every background paired with its own foreground (`bg-primary` with
+   `text-primary-foreground`), `border-input` on form controls, `border-border` on cards and dividers.
 5. **Verify** against the vertical's checklist before declaring done: token persists across
    reload, live data renders (or a real empty state), and purchases go through the Wix redirect.
 

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

@@ -0,0 +1,156 @@
+// Post-install deploy — run by base44.md STEP 1 with the vertical(s) the app needs:
+//   node deploy.cjs <vertical> [<vertical> …] --client-id <id> --metasite-id <id>
+//   (storefront | bookings | blog | cms | portfolio | pricing-plans | events | members)
+// Pass the two ids from the prompt and this writes src/rest/wix-config.js for you — see WRITE below.
+// Retyping those ids into the file by hand is how a storefront ships with a dead client id.
+// ONE mechanism: recursively copy `app/` -> /app/src. The shared transport (app/rest/wix-client.js,
+// wix-config.js) is copied always; then each named vertical's app/ (its UI + app/rest/ helpers).
+// Deploy every vertical the app actually uses, in one call or across several — an app that needs both
+// members and cms names both, and its CMS helpers then come from the skill instead of being
+// hand-written. Order matters only where two verticals ship a file at the SAME path (both have
+// components/…, pages/…): the first one listed wins, since the copy never overwrites. Verticals whose
+// file sets don't overlap (cms ships utils only, no UI) combine freely.
+// paths are the Base44 sandbox's /app. Re-running is non-destructive: it fills in only missing files,
+// never overwriting the agent's edits (see COPY), so a later call can add a vertical safely.
+// 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 REF = '/app/.agents/skills/wix-vibe-headless/references';
+const WIX_CONFIG = '/app/src/rest/wix-config.js';
+const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
+
+// force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
+// A re-run (e.g. the "files missing? re-run" fallback) then restores what's missing without
+// clobbering the agent's edits (wired App.jsx, home/header components) from the first deploy.
+const COPY = { recursive: true, force: false, errorOnExist: false };
+
+// --- members vertical only: replace leftover Base44 auth pages -------------------------------
+//
+// Base44 seeds src/pages/Login.jsx + src/pages/Register.jsx into every custom-auth-enrolled app
+// at APP CREATION, before any Wix skill ever runs (backend/app/user_apps/auth_templates/_loader.py
+// in the platform repo). The members vertical's own Login.jsx lands at that SAME path via the COPY
+// above, but COPY's force:false skips it because Base44's file is already there — so the Base44-auth
+// page silently survives instead of the Wix-auth one, and the app ends up with two half-wired auth
+// systems. There is no Wix Register.jsx at all (LoginForm's own "Sign up" tab covers registration),
+// so Base44's Register.jsx was never even in contention — it just sits there, wrong, either way.
+//
+// Fix both, but ONLY when the file currently on disk is still recognizably Base44's boilerplate
+// (imports base44Client / calls base44.auth.*). Never touch a file that's already the Wix version
+// or an agent's own customization — same "don't clobber" contract as COPY above, just evaluated on
+// content instead of mere existence.
+function isBase44AuthBoilerplate(path) {
+  if (!existsSync(path)) return false;
+  const src = readFileSync(path, 'utf8');
+  return src.includes('@/api/base44Client') || src.includes('base44.auth.');
+}
+
+// Each entry: the src/ file to repair, and the reference file that replaces it.
+// Login.jsx comes from the vertical's shipped pages; Register.jsx from references/members/install/
+// (a repair stub kept OUT of app/ — this vertical ships no /register route, so a fresh app with no
+// Base44 leftover must not receive it).
+const MEMBERS_AUTH_REPAIRS = [
+  { dest: '/app/src/pages/Login.jsx', src: `${REF}/members/app/pages/Login.jsx` },
+  { dest: '/app/src/pages/Register.jsx', src: `${REF}/members/install/Register.jsx` },
+];
+
+function replaceMembersAuthLeftovers() {
+  const result = {};
+  for (const { dest, src } of MEMBERS_AUTH_REPAIRS) {
+    const name = dest.split('/').pop().replace('.jsx', '').toLowerCase();
+    if (existsSync(src) && isBase44AuthBoilerplate(dest)) {
+      cpSync(src, dest, { force: true });
+      result[name] = 'replaced_base44_leftover';
+    } else {
+      result[name] = 'left_as_is';
+    }
+  }
+  return result;
+}
+
+// --- WRITE the credentials ----------------------------------------------------------------------
+//
+// The two ids arrive as flags so this script writes them once, character-for-character, instead of a
+// later hand-edit of the placeholder file.
+//
+// An id already in the file wins; the flags only fill what is unset. A host that writes this file
+// at app creation (Base44) has each id as an exact value rather than a copy read out of a prompt.
+// Per id, so a host that resolved one but not the other still gets the gap filled.
+//
+// This briefly worked the other way round for WIX_METASITE_ID, while Base44 could write a different
+// site than the business: it shared one field between the launch and a metasite it provisions per
+// app, and the launch's id lost. Fixed on that side, and the ids it stores now verify against the
+// site each launch came from, so the file is trusted again.
+function readWixConfig() {
+  if (!existsSync(WIX_CONFIG)) return {};
+  const src = readFileSync(WIX_CONFIG, 'utf8');
+  const pick = (name) => {
+    const v = (src.match(new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`)) || [])[1] || '';
+    return v.startsWith('<') ? '' : v;   // the shipped file's `<YOUR-…>` placeholders count as unset
+  };
+  return { clientId: pick('WIX_CLIENT_ID'), metaSiteId: pick('WIX_METASITE_ID') };
+}
+
+function writeWixConfig(clientId, metaSiteId) {
+  const body = [
+    '// Wix credentials — written by the skill\'s deploy step from the ids in your prompt.',
+    '// Safe to commit: WIX_CLIENT_ID is a public, buyer-facing id (it only mints anonymous visitor',
+    '// tokens); WIX_METASITE_ID just identifies the site.',
+    `export const WIX_CLIENT_ID = "${clientId}";`,
+    `export const WIX_METASITE_ID = "${metaSiteId}";`,
+    '',
+  ].join('\n');
+  writeFileSync(WIX_CONFIG, body);
+}
+
+// --- main ---------------------------------------------------------------------------------------
+
+// Accept one or many: `deploy.cjs members cms`. Duplicates collapse; order is preserved so the
+// first vertical listed wins any same-path file (the copy never overwrites).
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : null;
+};
+const clientId = flag('client-id');
+const metaSiteId = flag('metasite-id');
+// Verticals are the positional args — drop the flags and their values.
+const flagArgs = new Set(['--client-id', '--metasite-id', clientId, metaSiteId].filter(Boolean));
+const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
+const deployed = { verticals: [] };
+
+// Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/).
+if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);
+
+// Each named vertical — its app/ (UI + app/rest/ helpers) -> src/.
+const unknown = requested.filter((v) => !VERTICALS.includes(v));
+for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
+  if (!existsSync(`${REF}/${vertical}/app`)) continue;
+  cpSync(`${REF}/${vertical}/app`, '/app/src', COPY);
+  deployed.verticals.push(vertical);
+  if (vertical === 'members') deployed.authPagesFixed = replaceMembersAuthLeftovers();
+}
+
+if (unknown.length) {
+  deployed.error = `unknown vertical(s) ${unknown.map((v) => `"${v}"`).join(', ')} — expected: ${VERTICALS.join(', ')}`;
+}
+if (!requested.length) {
+  deployed.note = 'no vertical given — deployed the shared transport only; re-run: node deploy.cjs <vertical> [<vertical> …]';
+}
+
+const onDisk = readWixConfig();
+const finalClientId = onDisk.clientId || clientId;
+const finalMetaSiteId = onDisk.metaSiteId || metaSiteId;
+
+if (!finalClientId || !finalMetaSiteId) {
+  deployed.wixConfig = 'missing_ids — src/rest/wix-config.js is not configured; re-run with '
+    + '--client-id and --metasite-id rather than editing the file by hand';
+} else if (finalClientId === onDisk.clientId && finalMetaSiteId === onDisk.metaSiteId) {
+  deployed.wixConfig = 'already_set';
+} else {
+  writeWixConfig(finalClientId, finalMetaSiteId);
+  deployed.wixConfig = 'written';
+}
+
+console.log(JSON.stringify(deployed));

package/skills/wix-vibe-headless/install/pin-agents-md.cjs

@@ -0,0 +1,34 @@
+// Pin the skill location + project facts into /app/AGENTS.md so later turns (after the platform
+// build doc leaves context) still know the rules. Idempotent — safe to re-run; writes at most once.
+// Run once by base44.md STEP 1, separately from per-vertical deploys (deploy.cjs), so "copy a
+// vertical's files" and "record the project's ground rules" stay independent concerns.
+// .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, readFileSync, appendFileSync } = require('fs');
+
+const NOTE = `
+
+## This app — a Wix-managed headless frontend (built with the Wix skills)
+
+This project is the **frontend for a Wix-managed business** — a REST client that talks directly to a live Wix site over \`WIX_CLIENT_ID\`. The **Wix site is the source of truth** for all content and commerce; build and seed it only through the Wix connector and the skills below. **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+
+The Wix skills live under \`.agents/skills/\` — on ANY turn, read them from that exact path (ignore stray copies like \`agent/skills/\`).
+
+- \`wix-vibe-headless\` — **how the CLIENT is built AND how the site is seeded**: your vertical's UI client + REST scaffolds are already deployed into \`src/\`; one vertical per capability under \`references/<vertical>/\`, each with a \`seed/\` module that creates content over the connector:
+  - **storefront** — sell physical or digital products online.
+  - **bookings** — let customers book appointments or services with your business.
+  - **blog** — publish articles for visitors to read.
+  - **cms** — model and serve your own custom, structured content — for anything the other verticals don't cover.
+  - **portfolio** — showcase creative work in collections and project pages.
+  - **pricing-plans** — sell memberships or subscriptions to your service.
+  - **events** — publish events and handle RSVPs or ticket sales.
+  - **members** — let visitors create an account and sign in — this is **auth**.
+  - **restaurants** — publish a menu, take online orders, and manage table reservations.
+- \`wix-docs\` — **fallback** for **frontend code**, **backend code**, or **runtime / API management operations** alike: search + read the Wix API reference docs.
+`;
+
+const amd = '/app/AGENTS.md';
+const cur = existsSync(amd) ? readFileSync(amd, 'utf8') : '';
+const pinned = !cur.includes('Wix-managed headless frontend');
+if (pinned) appendFileSync(amd, NOTE);
+console.log(JSON.stringify({ agentsMdPinned: pinned }));

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

@@ -4,10 +4,14 @@ One file per AI-builder platform (Base44, Lovable, Bolt, v0, Manus, …). Each f
 **handoff prompt** the Wix Headless funnel hands to that platform after it creates the site +
 OAuth app: build the client, then seed/manage the business.
 
-`generic.md` is the **platform-agnostic** version — same flow (install skills → build client →
-seed/manage → wrap up) with no assumptions about a specific platform's tooling. Use it as the
-default/fallback for platforms without their own tuned file; `base44.md` is the Base44-specific
-one (its exec tool, secret store, pre-configured connector, etc.).
+`generic.md` is the **platform-agnostic** version and the default/fallback for any platform without
+its own tuned file. It is also a **lens over the skill**: the skill's `SKILL.md` + per-vertical
+`INSTRUCTIONS.md` are written for Base44's stack (Vite + react-router + `.jsx`, files pre-copied into
+`src/`), so `generic.md` tells a non-Base44 agent what the skill's three real assets are (the `rest/`
+client layer, the field-shape/route-pattern data contract, the `seed/` functions), which Base44-isms
+to ignore/translate, and the hard rule to **generate into the existing stack — never convert the
+framework**. `base44.md` is the Base44-specific one (its exec tool, secret store, pre-configured
+connector, `deploy.cjs` copy path, etc.).
 
 These are hosted (served at `https://www.wix.com/skills/vibe-headless/platforms/<platform>.md`)
 so the funnel loader can pass a short pointer to the prompt instead of inlining the whole