feat(sp-wix): Wix × Stripe Projects business-integration skill

skills/sp-wix/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: sp-wix
+description: "Connect Wix business services (Stores, Blog, CMS, Forms, Events, Bookings, Pricing Plans) to a Stripe Projects app. Use AFTER `stripe projects add wix/*` has provisioned a Wix metasite + synced its credentials to `.env`. Given the metasite and the user's intent, this skill runs the Wix business flow — infers which Wix capabilities the app needs, installs the apps, seeds backend content — then returns an SDK-integration guide (how to call Wix from the frontend) for the host agent to use. The host keeps ownership of the frontend, the build, and the hosting. Triggers: set up Wix in this Stripe project, add a Wix store/blog/CMS/forms/events/bookings/pricing-plans backend, connect Wix Headless to my Stripe app, provision Wix content for this project, I added wix with stripe projects now wire it up. NOT for: building a new Wix-hosted site from scratch (use wix-headless), or anything outside a Stripe Projects app."
+allowed-tools:
+  - Bash(curl *)
+  - Bash(ls *)
+  - Bash(cat *)
+  - Bash(grep *)
+  - Bash(head *)
+  - Bash(test *)
+  - Read
+  - Write
+---
+
+# Wix Headless × Stripe Projects
+
+This skill connects **Wix business services** to an app managed by [Stripe Projects](https://docs.stripe.com/projects). The host agent (Claude Code / Cursor / an MCP agent, driven by Stripe's flow) owns the conversation, the frontend, the build, and the hosting.
+
+**This skill's job is to configure the Wix backend**: infer the needed capabilities, **install the Wix apps**, **seed the backend content**, return an integration guide describing how to call Wix from the frontend, and — once the site is deployed — **register the deployed origin on the OAuth app** so the frontend is actually allowed to call Wix. The configured backend is the work; the guide just describes it. A run is complete only when **Setup and Seed have run**, the guide has been emitted, and the deployed origin has been registered (or, if deployment is out of this flow, the user has been told it's required).
+
+## Preconditions (the host provides these — we read, never create)
+
+1. **A Stripe Project with Wix connected** — `stripe projects add wix/*` has run, provisioning a metasite + a headless OAuth app and syncing credentials to `.env`: `WIX_WIX_CLIENT_ID`, `WIX_WIX_CLIENT_SECRET`, `WIX_WIX_METASITE_ID` (see `references/AUTHENTICATION.md`).
+2. **The user intent** — free text describing what Wix should power ("add a store", "blog + contact form", "persist my app's data").
+3. *(Optional)* the project on disk — read-only, to sharpen brand/capability inference.
+
+If the Wix credentials are absent, Wix isn't connected in this project — **stop with a clear error**.
+
+## What this skill does
+
+When invoked, **run these four steps in order, start to finish.** Steps 1–3 are the skill's actual work — they execute against the metasite over `curl`; step 4 reports the result. Open `DISCOVERY.md` and begin.
+
+1. **Discovery** (`references/DISCOVERY.md`) — infer the capability set + brand + per-capability intent from the user's words, then drive straight into Setup.
+2. **Setup** (`references/SETUP.md`) — **install** the Wix apps those capabilities need on the metasite.
+3. **Seed** (`references/SEED.md`) — **create** the backend content for each capability (products, posts, collections + items, forms).
+4. **Handoff** (`references/SDK_HANDOFF.md`) — **only after Setup and Seed have run**, return the integration guide: the SDK bootstrap, per-capability call shapes, the **seeded IDs** (which exist only because Seed ran), and the `@wix/*` package list.
+5. **Register origin** (`references/REGISTER_ORIGIN.md`) — **after the site is deployed**, register its URL on the OAuth app (the admin call `init` normally does for hosted sites). Do it **once per URL** (skip if already registered). If deployment isn't part of this flow, **flag to the user** that this step is required before the frontend can call Wix.
+
+Steps 1–4 run in one pass; step 5 happens once the deployed URL exists (the skill performs it if it sees the deploy, otherwise flags the user). The guide in step 4 describes the backend that Setup and Seed built. Each Wix call uses a token minted from `.env` (`references/AUTHENTICATION.md`). The skill runs non-interactively, inferring from the user's words rather than asking.
+
+## Path resolution
+
+Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL.md`); hold the absolute path in scratch.
+
+| What | Path |
+|---|---|
+| Authentication (token mint + REST contract + ladder) | `<SKILL_ROOT>/references/AUTHENTICATION.md` |
+| Vertical index (intent matching + per-vertical site spec) | `<SKILL_ROOT>/references/CAPABILITIES.md` |
+| Discovery (infer capabilities + brand + intent) | `<SKILL_ROOT>/references/DISCOVERY.md` |
+| Setup (install apps) | `<SKILL_ROOT>/references/SETUP.md` |
+| Seed (create backend content) | `<SKILL_ROOT>/references/SEED.md` |
+| SDK-integration handoff (the returned document) | `<SKILL_ROOT>/references/SDK_HANDOFF.md` |
+| Register the deployed origin on the OAuth app (post-deploy) | `<SKILL_ROOT>/references/REGISTER_ORIGIN.md` |
+
+**Start a run by opening `DISCOVERY.md`.**
+
+## Where the *how* comes from
+
+This skill has **no skill upstream** — the *how* is read from the **live Wix docs** at `dev.wix.com/docs`, fetched as raw markdown via `curl` (append `.md` to any docs URL; menu pages list child links, content pages carry the schema):
+
+- **Seed** reads the **REST docs** for each capability's create method — navigated from the Business Solutions index (`api-reference/business-solutions.md`) per the mechanism in `SEED.md` (Forms lives under `api-reference/crm/forms.md`).
+- **Handoff** links the **SDK docs** for each capability's API shape, and supplies the runtime package set from the inlined map in `SDK_HANDOFF.md` (the SDK `.md` pages don't expose `@wix/*` import strings to navigation, so packages are mapped, not navigated).
+
+Setup carries its app-install call (and the appDefId constants) inline in `SETUP.md`; `CAPABILITIES.md` is the vertical index that lets Discovery match intent **and** declares, per built vertical, the *Required site features* + *Implementation checklist* that Seed enables (backend-backed features) and the Handoff carries into the guide (so the host builds a complete site, not a bare data dump). This skill carries the *what* (which capabilities, how much content, what a finished site includes) and reads the *how* off the docs.

skills/sp-wix/references/AUTHENTICATION.md

@@ -0,0 +1,52 @@
+# Authentication (Stripe-Projects → Wix)
+
+Every Wix call this skill makes is a plain `curl` against `wixapis.com` with a bearer token. The credentials come from the project's `.env` (synced by Stripe Projects when Wix was connected), and the token is minted directly from the OAuth client-credentials grant.
+
+## Inputs from `.env`
+
+Stripe Projects namespaces each provider's vars, and Wix's own names already begin with `WIX_`, so a real provision yields a **doubled prefix**:
+
+| Var                     | Role                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `WIX_WIX_CLIENT_ID`     | the OAuth app `client_id` — also the frontend `OAuthStrategy({ clientId })`                       |
+| `WIX_WIX_CLIENT_SECRET` | the OAuth app `client_secret` — **server-side only**; mints the token, never goes to the frontend |
+| `WIX_WIX_METASITE_ID`   | the metasite id → the `wix-site-id` header on every site-scoped call                              |
+
+The plain `WIX_*` names are accepted as a fallback (in case the provider definition changes). Read them at runtime. If `client_id`/`client_secret` are absent, Wix isn't connected in this project — **stop with a clear error**.
+
+## Minting the token — inline, secret stays out of context
+
+Run this as a **single Bash call**. It sources `.env` *inside the shell*, so the command text references `$WIX_WIX_CLIENT_SECRET` but the secret value is never typed, printed, or returned. The minted token is written to a tmp file so later calls reuse it **without re-minting and without the token entering the model context**:
+
+```bash
+set -a; . ./.env; set +a
+curl -sS -X POST "https://www.wixapis.com/oauth2/token" \
+  -H "Content-Type: application/json" \
+  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"${WIX_WIX_CLIENT_ID:-$WIX_CLIENT_ID}\",\"client_secret\":\"${WIX_WIX_CLIENT_SECRET:-$WIX_CLIENT_SECRET}\"}" \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])" > /tmp/wix_token \
+  && test -s /tmp/wix_token && echo "token minted" || echo "MINT FAILED — Wix not connected, or app/creds invalid"
+```
+
+That endpoint returns `{ "access_token": "<…>", "token_type": "Bearer", "expires_in": 14400 }`. `instance_id` is **optional and omitted**. The token is a real OAuth token with a **4-hour expiry**.
+
+> **Shell state does not persist between Bash calls** — that is *why* the token goes to `/tmp/wix_token`. Mint once at the start of the run; every later call reads it back. Do **not** import the CLI "byte-identical, never re-mint" lore — each mint here returns a *different, equally valid* token; "mint once" is for simplicity, not because re-minting is pointless.
+
+## REST call shape
+
+Every later call re-sources `.env` (for the non-secret metasite id) and reads the token from the tmp file — both cheap, both keep secrets out of context:
+
+```bash
+set -a; . ./.env; set +a
+TOKEN=$(cat /tmp/wix_token)
+SITE_ID="${WIX_WIX_METASITE_ID:-$WIX_METASITE_ID}"
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required.
+- **`wix-site-id: $SITE_ID`** — required by every site-scoped family (Stores v3, CMS v2, Blog v3, Forms v4, Apps-Installer v1, …). Harmless where unread; include it always.
+- **`Content-Type: application/json`** — on every POST/PATCH body.

skills/sp-wix/references/CAPABILITIES.md

@@ -0,0 +1,67 @@
+# Wix vertical index
+
+A catalog of the Wix business verticals. It does two jobs:
+
+1. **Discovery** maps the user's words to the right vertical(s) — read every *Intent* line against what they asked for, and pick each vertical that genuinely fits.
+2. For the verticals this skill builds end-to-end, it also says **what a complete site for that vertical looks like** — the features it must have and the details that make it feel finished — so the handoff asks the host for a *real* site, not a bare data dump.
+
+This file is **the what, never the how** — plain language only. No endpoints, methods, payloads, appDefIds, or SDK packages. The *how* lives in the live docs (Seed navigates the REST docs; the Handoff navigates the SDK docs); the *which apps to install* lives in `SETUP.md`.
+
+Each built vertical has three parts:
+
+- **Intent** — the words that point to it.
+- **Required site features** — the surfaces and capabilities the site must have to be usable. These are non-negotiable for a complete site; if one needs a backend feature switched on, Seed sets it up, and the Handoff tells the host to build the rest.
+- **Implementation checklist** — the presentation details a finished site shows, so it doesn't feel half-built. The Handoff carries these into the guide it returns.
+
+## Built verticals — installed, seeded, and described in the Handoff
+
+The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · pricing-plans** (with `forms` as the floor when nothing richer is named).
+
+### stores — sell products
+- **Intent:** sell / shop / products / catalog / merch / store.
+- **Required site features:** a product list or grid; a page per product; categories to browse by; a cart; a checkout.
+- **Implementation checklist:** show each product's image, name, and price; show options and variants (size, colour…) where they exist; show availability / out-of-stock; a quantity picker and an add-to-cart that updates a visible cart; the product description; link each product to its category.
+
+### blog — publish posts
+- **Intent:** blog / posts / articles / publication / news.
+- **Required site features:** a list of posts; a page per post; readers can leave **comments** on a post; categories or tags to browse by topic.
+- **Implementation checklist:** show the **author** (name and photo) on each post; show the publish date and the reading time; show the cover image; render the full formatted content — headings, images, quotes, lists — not flattened to plain text; show the post's category and tags; a clear path back to the full list.
+
+### cms — structured content collections
+- **Intent:** collection / directory / portfolio-as-data / structured content / "persist my app's data".
+- **Required site features:** an index/list view of the collection; a detail page per item. (Visitor reads are public; visitor writes go through a form.)
+- **Implementation checklist:** show each item's main fields with clear labels; link the list to each item's detail page; show a sensible empty state when there are no items yet.
+
+### forms — capture leads
+- **Intent:** contact / lead / signup / waitlist / "let people reach me" / nothing dynamic named.
+- **Required site features:** a visible form; a confirmation after submitting; basic field validation.
+- **Implementation checklist:** render every field with a clear label; mark which fields are required; a clear submit button; show a thank-you / success state after sending; show a friendly message if the submit fails.
+
+### events — events and registration
+- **Intent:** event / ticket / RSVP / registration / attendees.
+- **Required site features:** a list of events; a page per event; a way to register or RSVP.
+- **Implementation checklist:** show each event's title, date and time, and location; show the description; show ticket types where they exist; a register/RSVP action; a confirmation after registering.
+
+### bookings — appointments and classes
+- **Intent:** book / appointment / schedule / class / session / reserve a slot / reserve a table.
+- **Required site features:** a list of services; a page per service; a way to pick a time and book it.
+- **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
+
+### pricing-plans — memberships and subscriptions
+- **Intent:** membership / subscription / plans / paid tiers.
+- **Required site features:** a plans / pricing page; a way to choose and subscribe to a plan.
+- **Implementation checklist:** show each plan's name, price, and billing cycle; list what each plan includes (the perks); a clear "choose plan" action; highlight a recommended tier where it makes sense.
+
+## Other verticals — recognized for intent, not yet wired
+
+If a user's intent points squarely at one of these, surface it plainly as **not-yet-wired** rather than forcing a poor fit. Extending the skill to one means adding its install in `SETUP.md` and its seed *what* in `SEED.md`, then giving it a full section above.
+
+- **eCommerce** — the shared cart, checkout, orders, and payments layer the catalog verticals (Stores, Bookings…) plug into; rarely chosen alone, it rides along when a purchase flow is needed. *Intent: checkout / cart / "let people buy".*
+- **restaurants** — menus and online food ordering; a table-reservation intent goes to **bookings** instead. *Intent: menu / restaurant / order food / dine-in.*
+- **forum** — community discussion boards: categories, threads, member posts. *Intent: forum / community / discussion board.*
+- **portfolio** — showcase collections of projects and work. *Intent: portfolio / showcase / gallery of projects / creative work.*
+- **donations** — donation campaigns and contributions. *Intent: donate / fundraise / campaign / nonprofit.*
+- **gift-cards** — issue and redeem stored-value gift cards. *Intent: gift card / store credit / voucher.*
+- **coupons** — discount codes and promotions applied at checkout. *Intent: coupon / promo code / discount.*
+- **benefit-programs** — loyalty/benefit programs that grant members perks. *Intent: loyalty / rewards / member perks / benefits.*
+- **suppliers-hub** — supplier-side B2B product catalog management. *Intent: supplier / wholesale / B2B catalog.*