/wix-headless-kit

An existing site: a new frontend for a site that already has its content

Read when the brief names a Wix site by its id. Nothing here is seeded: the site owns its content and the frontend reads it live. (A project downloaded from Wix whose .env.local declares a migration is the other way to arrive at an existing site: guides/migration.md; the reading part below applies there too, against the migrated site.) <SKILL_ROOT> is the installed skill folder; the shipped code is under <SKILL_ROOT>/templates/ (SKILL.md, "The run").

Read the site, then run attach. First, one call tells you what the site is — its name, currency, and the Wix apps installed on it:

curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
  -H "Authorization: $(npx -y @wix/cli@latest token)" -H 'Content-Type: application/json' \
  -d '{"siteId": "<siteId>"}'

The installed apps name the verticals (Wix Stores → storefront, Wix Bookings → bookings, and so on per the Verticals table); the brief picks among them. Then one deterministic call, same shape as setup (SKILL.md step 3):

node <SKILL_ROOT>/install/attach.mjs --site <siteId> --business-name "<site name>" --vertical <vertical>[,<vertical>]

init/wix create always create a site, so they are not used here. attach does what they do after creating one — the site's OAuth app, Wix hosting, wix.config.json — against the site given, copies the first vertical's composed template, deploys the rest, and starts the install detached. No seed runs and nothing on the site changes: the content is the site's own, read live through the deployed data layer. attached also says whether a frontend is already serving at the site's address (frontend.serving, with the release date). When it is, a wix release from this project replaces it — the old deployment keeps its own address and production can be pointed back, but the user's site changes. Tell the user before you release, with the address and the date; if the brief did not ask for a new frontend, ask first and wait. Say it again when you close.

Get the measure of the site before you design. Enough to know what you are building for: what the chosen verticals will render, roughly how much of it, and what it is like — six items in three groups design differently from six hundred. Run the vertical's reader:

node <SKILL_ROOT>/templates/<vertical>/seed/read-site.mjs --site <siteId> [--limit <n>]

It prints one JSON: whether the vertical's app is installed, counts, one page of each entity with the fields the pages render, and calls, the requests it made with their documentation URLs. The lists are one page; the counts are the site.

When the brief needs a read the script does not make, it is a build-time call with the site's token, sent raw as the Authorization header (the account token from the call above does not scope to a site), minted inline in each command — -H "Authorization: $(npx -y @wix/cli@latest token --site <siteId>)" — and never written to a file, not in the project and not in /tmp. The rule above applies in full: not one of these calls comes from memory. Read the request where it is written, then call. Where to read, in this order:

• The reader, templates/<vertical>/seed/read-site.mjs — the reads the pages make, as literal calls with their documentation URLs.
• wix-manage, at .agents/skills/wix-manage/ — REST recipes for managing a site's business solutions: exact endpoint, method and payload per operation, curl included. Its SKILL.md is the index, by solution; open the recipe for the vertical's solution.
• wix-docs, at .agents/skills/wix-docs/ — the Wix API reference, reached by search, not by browsing files: the skill folder holds the how-to, not the pages. Open its SKILL.md; it gives one curl to semantic search (POST /mcp-docs-search/v1/docs/search/markdown, natural-language search_term) that returns condensed method docs — endpoint, request example, response shape — and the rule that any dev.wix.com/docs/… URL plus .md is the full page. Progressive: search first, read the full document only when the hit lacks what you need. If what you opened does not have the call, go to the next; do not try a variant, and do not build one from a call you did find: the path and body you send are copied from the output you read or they are not sent.

In a folder that already holds a project (a package.json or index.html, no wix.config.json), attach writes the config into it and deploys for --stack instead of scaffolding; pass the stack resolved in SKILL.md step 1. A frontend that will be hosted elsewhere (Vercel, your own server) runs attach with --hosting self --origin <url>[,<url>]: no Wix hosting is created, and the origins go on the OAuth app's allow-list so checkout can return to them; add the public origin when it goes live. Then SKILL.md steps 4 and 5 as for any run, with the install marker the only one to wait on.