@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -0,0 +1,177 @@
+# Wix Managed Headless — Base44 build instructions
+
+You are building a **Wix Managed** headless site inside Base44 — the business is described in your
+initial prompt, and the Wix connector is already configured; use it for all admin API calls.
+
+Your Wix client id is in your prompt — a public, buyer-facing credential (anonymous visitor tokens
+only), safe in the frontend; use it directly for the Wix client setup.
+
+> **`wix-vibe-headless` and `wix-docs` are the complete build and seed path for this app — the Wix connector supplies the token for admin API calls.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
+
+Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3).
+
+## STEP 1 — Install the Wix skills locally
+
+Install two skills — they land under `.agents/skills/`:
+- **`wix-vibe-headless`** — the client build **and** seed guide (STEPs 3–4): your main source of
+  truth. Seeding lives here too, per-vertical under `references/<vertical>/seed/`.
+- **`wix-docs`** — a **fallback**: search + read the Wix API docs for anything `wix-vibe-headless`
+  doesn't cover.
+
+Install via the skills CLI — run this through exec_tool, exactly as written. It installs the two
+skills, then runs `deploy.cjs <vertical…>` (lays the shared transport + **each** listed vertical's
+REST scaffolds and UI client into `src/`) and `pin-agents-md.cjs` (pins the project's AGENTS.md
+note so later turns keep the rules).
+
+**Set `VERTICALS`** to what the prompt asks for (too vague to tell? do STEP 2 first, then set it):
+
+| vertical | pick it when the app needs to |
+|---|---|
+| `storefront` | sell products |
+| `bookings` | take appointments or service bookings |
+| `blog` | publish articles |
+| `events` | publish events with RSVPs or ticket sales |
+| `portfolio` | showcase creative work |
+| `pricing-plans` | sell memberships or subscriptions |
+| `restaurants` | show a menu, take orders, book tables |
+| `members` | let visitors sign in — this is **auth** |
+| `cms` | keep its own structured content — user submissions, galleries, listings, anything the rows above don't already cover |
+
+**List every vertical the app actually uses** — one is the common case, and name more when the intent
+spans them, so all their scaffolds come from the skill rather than being written by hand. Anything the
+app stores itself needs `cms`, and anything where visitors sign in needs `members`, so those two often
+join whichever vertical is the main one. Adding one later is fine too: re-run with the extra name (the
+copy only fills in missing files).
+
+```js
+const { execSync } = require('child_process');
+const { readdirSync } = require('fs');
+const VERTICALS = ['storefront'];        // ← set from the prompt; list every vertical the app uses
+// const VERTICALS = ['members', 'cms']; // ← e.g. visitors sign in AND the app stores what they submit
+const results = {};
+for (const skill of ['wix-vibe-headless', 'wix-docs']) {
+  try {
+    const out = execSync(`CI=1 npx -y skills add wix/skills/skills/${skill} --yes 2>&1`,
+      { cwd: '/app', timeout: 60000, shell: '/bin/bash' }).toString().replace(/\x1b\[[0-9;]*m/g, '');
+    results[skill] = /installed 1 skill|found 1 skill/i.test(out) ? 'success'
+      : out.includes('No valid skills') ? 'not_found' : 'unknown';
+  } catch (e) { results[skill] = 'error: ' + e.message; }
+}
+// Deploy the shared transport + each listed vertical's scaffolds/UI into src/.
+const deploy = execSync(`node /app/.agents/skills/wix-vibe-headless/install/deploy.cjs ${VERTICALS.join(' ')}`, { cwd: '/app' }).toString();
+// Pin the project's AGENTS.md note (idempotent) so the rules survive after this doc leaves context.
+const agentsMd = execSync(`node /app/.agents/skills/wix-vibe-headless/install/pin-agents-md.cjs`, { cwd: '/app' }).toString();
+return { results, installed: readdirSync('/app/.agents/skills'), deploy: JSON.parse(deploy), agentsMd: JSON.parse(agentsMd) };
+```
+
+Read the skills with **`read_file`** (rooted at `/app` → workspace-relative path, e.g.
+`.agents/skills/wix-vibe-headless/SKILL.md`; absolute `/app/...` fails — exec_tool/shell wants
+absolute). Prefer it over `cat`/exec_tool and web-fetch, which cap output (~5000 chars) and
+truncate. Always read from **`.agents/skills/` exactly**, on later turns too — don't guess; ignore
+stray copies like `agent/skills/`.
+
+## STEP 2 (optional) — Brief doesn't say what to build? Read the site
+
+Only when the business description is vague or missing (else skip to STEP 3). Don't guess the Wix
+Business Solution — **read the site in one call** via the connector (exec_tool):
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+const res = await fetch("https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown", {
+  method: "POST",
+  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+  body: JSON.stringify({ siteId: "<metasite id from your prompt>" }),
+});
+return (await res.json()).markdown;
+```
+
+It returns a markdown report — installed apps (by name), status, URL, locale, CMS collections
+([docs](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown.md)).
+Build for the installed apps' solutions (several → prioritize by the user's words and which holds
+real, non-sample content); the same output drives STEP 4's seeding — never seed guessed ones. If it
+fails or shows nothing relevant, ask the user what they offer.
+
+## STEP 3 — Build the client
+
+Read `.agents/skills/wix-vibe-headless/SKILL.md` and follow it **EXACTLY** — the single source of
+truth for how the client is built.
+
+**REST scaffolds are already in `src/rest/`** (STEP 1). Write `src/rest/wix-config.js` with your
+`WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the one place both ids live (a single write,
+nothing to read). Some
+verticals also ship a **ready UI client** under `src/` (STEP 1 deployed it) — theme + wire it per
+`INSTRUCTIONS.md`, don't rebuild. STEP 1 already deployed these files — **don't `read_file` the
+deployed component/page source to inspect them**; every field shape is in `INSTRUCTIONS.md`. Read a
+deployed file only on a real fallback (an error, or a field the snippets don't cover).
+
+**`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.
+
+## STEP 4 — Manage and seed the business
+
+**Never delete or clean up anything on the user's site — seeding is additive only.** It's a live
+user-owned business, so never delete or overwrite existing content, even apparent sample data. If a
+cleanup truly seems needed, ask the user first.
+
+Seed by calling your vertical's ready-made seed module — read
+`.agents/skills/wix-vibe-headless/references/<vertical>/seed/SEED.md` and load its `seed-*.js` via
+its loader snippet (build-time exec_tool); call its functions with your data. Gaps or an unexpected
+shape → the **`wix-docs`** skill.
+
+**Auth for these admin calls is the already-configured Wix connector — nothing else.** Get its
+access token and send it as a bearer token; do **not** hand-roll a token getter (e.g.
+`getAdminToken()`), install/run the Wix CLI (`@wix/cli`), or device-login (no managed-project auth
+flow applies to Base44):
+
+```js
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+// then: fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" }, ... })
+```
+
+Inline via exec_tool, `base44` is already declared — use it directly; do **not** import
+`@base44/sdk`, re-declare it, or call `createClient()` (that's for standalone `.js` files only;
+inline it throws *"Identifier 'base44' has already been declared."*).
+
+**Entity images.** For image-bearing entities (store products, blog covers, bookings services,
+restaurant items, portfolio projects, event heroes, CMS items), generate with **Base44's built-in
+image generation**, then attach via the vertical seed module's image-attach step — `wix-docs` if the
+module doesn't cover that entity.
+
+**Seed images with the FINAL url, in one call.** Seeding writes to Wix, so use the real
+`https://media.base44.com/...` url from the **completed** `generate_image` result and pass it straight
+into your single `setupStore`/seed call (images included). A still-generating `/__generating__/<id>.png`
+placeholder is not a real url — Wix can't fetch it. `generate_image` runs in the background while you
+build the client, so the urls are ready by the time you seed.
+
+The connector + seeding are **admin-only** (STEP 4) — **not** part of the client, which is built
+solely per the `wix-vibe-headless` skill.
+
+## Parallelism
+
+Run STEP 3 and STEP 4 in parallel — building and seeding are independent. Within each, also
+parallelize independent work (API calls, multiple entities).
+
+## STEP 5 — Wrap up
+
+Once the site is built and seeded:
+
+1. **Mount the preview-only manage banner** (required; links the app to its Wix back office; shipped,
+   self-gates to the preview, never on the published site): render the `<WixManageBanner/>` component
+   in your Layout's fixed top region, above the header, per your vertical's INSTRUCTIONS STEP 4.
+2. **Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (substitute your
+   metasite id) to complete setup in Wix (required), and mention that the preview shows a dismissible
+   top banner linking to this same dashboard.
+
+**Preview briefly, don't chase images.** A quick render check is enough. Generated images show as
+alt-text/broken in this preview because `generate_image` returns a `/__generating__/…` placeholder —
+the platform swaps every placeholder for the final url **automatically at the end of the turn**
+(failed ones get a stock fallback), in your own components and the seeded data alike. So a broken
+image in the preview is expected and already handled: **do NOT swap, re-seed, re-attach, or debug
+image urls.** Hand-editing a placeholder `src` is wasted work and just risks find_replace errors on
+urls that are about to be replaced anyway. Leave them and finish.
+
+## Later admin requests
+
+For any later admin/management request, work as in STEP 4: your vertical's seed module first, else
+`wix-docs` — all over the connector.

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

@@ -0,0 +1,122 @@
+# Wix Managed Headless — build instructions (any stack)
+
+You are building a **Wix Managed** headless site — the business, your `WIX_CLIENT_ID`, and metasite
+id are in your prompt. This skill is **client-only REST** over the public `WIX_CLIENT_ID`
+(visitor-facing, safe in the browser) — no `@wix/sdk`, no backend, no build step.
+
+## What you've got in the skill
+
+The docs were authored for **one host stack** (Vite + react-router, `.jsx`, files pre-copied into
+`src/`) — you may be on another, so **adapt these assets to your stack; don't copy the host's setup.**
+Everything is under `.agents/skills/wix-vibe-headless/references/`.
+
+**Shared transport — both files, used by every vertical (`shared/app/rest/`):**
+
+| file | what's in it |
+|---|---|
+| `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. |
+
+**Every `references/<vertical>/` holds the same four things:**
+
+- `app/rest/wix-*.js` — the vertical's **data layer**: named calls carrying the exact request/response
+  **shapes**, fieldsets, and paging.
+- `app/{components,pages,hooks,context}/…` — a **reference UI** (+ hooks/providers) built on that data
+  layer; the field shapes and route patterns it uses (e.g. `/product/:slug`) are the data contract.
+- `seed/seed-*.js` — build-time **seeding functions** that create content.
+- `INSTRUCTIONS.md` — the vertical's build guide + field-shape snippets; `seed/SEED.md` — how the seed
+  module is run.
+
+**The nine verticals — data layer (`app/rest/`) + seed module (`seed/`):**
+
+| vertical | `app/rest/` data layer | seed module |
+|---|---|---|
+| storefront | `wix-store-catalog.js`, `wix-store-cart.js` — products & variants; server cart + checkout redirect | `seed-store.js` |
+| bookings | `wix-bookings-services.js`, `wix-bookings-checkout.js` — services/categories/slots; booking + checkout | `seed-bookings.js` |
+| blog | `wix-blog.js` — posts (list + by-slug), categories, tags | `seed-blog.js` |
+| events | `wix-events-browse.js`, `wix-events-registration.js` — events & categories; RSVP / ticketing + checkout | `seed-events.js` |
+| portfolio | `wix-portfolio.js` — collections, projects, galleries | `seed-portfolio.js` |
+| restaurants | `wix-restaurants-menu.js`, `-ordering.js`, `-reservations.js` — menu; online ordering; table reservations | `seed-restaurants.js` |
+| cms | `wix-cms.js` — Wix Data collections: list / detail / filter + form CRUD | `seed-cms.js` |
+| pricing-plans | `wix-pricing-plans.js` — plans list + subscribe/checkout | `seed-pricing-plans.js` |
+| members | `wix-members-auth.js` — custom login/signup (email+password, social, SSO), session, account | *(none — members sign up at runtime; nothing to seed)* |
+
+Anything in the docs about the **host's own setup** — copying files into `src/`, its `@/` alias, its
+`import.meta.env` flags, a theming file, its build/exec/connector tooling — is that host's, not a
+rule: **adapt it to your stack or ignore it.** The `SKILL.md` **"shared model"** (public-client-id
+auth, money = objects → render `formattedValue`, visitor token = cart identity, member login swaps
+the token set) is **universal — follow it as-is**.
+
+## The flow — install → build client → seed → done
+
+Run **build the client** (step 2) and **seed** (step 3) in parallel; parallelize independent work within each.
+
+### 1 · Install the skills
+
+Two skills, into `.agents/skills/`: **`wix-vibe-headless`** (this build guide + the seed modules —
+self-contained) and **`wix-docs`** (fallback to search/read the Wix API reference).
+
+```bash
+CI=1 npx skills@latest add wix/skills/skills/wix-vibe-headless --yes
+CI=1 npx skills@latest add wix/skills/skills/wix-docs --yes
+```
+
+### 2 · Build the client
+
+Pull the whole client reference into context in two reads — **this is basically your prompt: it's all
+the client code you need.** Build the client from it in your own stack's idiom (your router, file
+extensions, design tokens), and set `WIX_CLIENT_ID` + `WIX_METASITE_ID` in `wix-config`.
+
+```bash
+V=<vertical>   # the vertical you're building
+
+# utils — transport + data layer (plain fetch, already SSR-guarded; use ~as-is)
+find .agents/skills/wix-vibe-headless/references/shared/app/rest \
+     .agents/skills/wix-vibe-headless/references/$V/app/rest \
+     -type f -name '*.js' -exec tail -n +1 {} +
+
+# components/pages — a reference UI (rebuild for your framework; keep the field shapes + route patterns)
+find .agents/skills/wix-vibe-headless/references/$V/app \
+     -type f \( -name '*.jsx' -o -name '*.js' \) -not -path '*/rest/*' -exec tail -n +1 {} +
+```
+
+### 3 · Seed the content
+
+**⛔ NO CLEANUP — EVER.** Strictly **additive**: never delete, reset, or overwrite anything on the
+user's live site — not even apparent sample/demo content. If something looks wrong, leave it and tell
+the user.
+
+**Auth** (the public client id won't do): if your platform has a **built-in Wix connector**, use it
+(it holds the credential). Otherwise take a **Wix API key** into your secrets manager (never hardcode
+or commit) — create one at **[account API keys → Add key](https://manage.wix.com/account/api-keys/addkey)**
+([how-to](https://dev.wix.com/docs/api-reference/articles/authentication/api-keys/generate-an-api-key)) —
+and send it **raw as `Authorization` (no `Bearer`)** with a **`wix-site-id`** header (`wix-account-id`
+only for account-level APIs — one, not both):
+
+```bash
+curl -X POST 'https://www.wixapis.com/stores/v3/products/query' \
+  -H 'Authorization: <API_KEY>' -H 'wix-site-id: <METASITE_ID>' \
+  -H 'Content-Type: application/json' -d '{"query":{"cursorPaging":{"limit":10}}}'
+```
+
+Pull the seed code into context — **this is your seeding prompt: it's all the code you need.** Run
+these functions (adapting the exec + auth to your platform) to create the content:
+
+```bash
+V=<vertical>
+find .agents/skills/wix-vibe-headless/references/$V/seed -name '*.js' -exec tail -n +1 {} +
+```
+
+They encode the Wix API sequences (incl. app-install + provisioning-race handling); use `wix-docs`
+for anything they don't cover. Content queries return `REQUIRED_APP_NOT_INSTALLED` until the app is
+installed + seeded (expected; the seed modules install it first). Image seeding = two Wix Media calls
+(`generate-upload-url` → `PUT` the bytes) before attaching.
+
+### 4 · Done
+
+Mount the preview-only manage banner (regenerate `WixManageBanner` for your stack — it reads
+`WIX_METASITE_ID` from `wix-config`, already set in step 2, and self-hides while it's still the
+placeholder; mount above the header, SSR-safe, portable preview-gate, **never on the published
+site**), then tell
+the user to open `https://manage.wix.com/dashboard/{metaSiteId}` to finish setup in Wix (payments,
+content).