@wix/agent-skills 1.20.1 → 1.22.0

package/skills/wix-headless-fast/cold-start/bootstrap.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ── tiny event protocol (one JSON object per line) ───────────────────────────
+const emit = (event, extra = {}) =>
+  process.stdout.write(JSON.stringify({ event, ...extra }) + '\n');
+const fail = (event, extra = {}) => {
+  emit(event, { ok: false, ...extra });
+  process.exit(1);
+};
+
+// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
+const isWin = process.platform === 'win32';
+const bin = (name) => (isWin ? `${name}.cmd` : name);
+const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
+
+// Force the CLI into non-interactive "agent" mode. Without an agent signal in
+// the env, `wix login` renders an interactive Ink TUI (device code + keypress)
+// that needs a raw TTY and crashes in an agent sandbox — and it never emits the
+// JSON login events this script forwards. The CLI uses @vercel/detect-agent,
+// whose first check is the AI_AGENT env var, so setting it guarantees agent mode
+// (and the awaiting_user/success/logged_in events) for every child we spawn.
+// Respect an existing value so a known runner (claude, cursor, …) keeps its name.
+const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-fast-skill' };
+
+// Where the detached login parks its output between runs. It has to outlive this
+// process, so it can't be a pipe and can't live in the project.
+const STATE_DIR = join(tmpdir(), 'wix-headless-fast-login');
+const LOG = join(STATE_DIR, 'login.log');
+const PIDFILE = join(STATE_DIR, 'login.pid');
+
+// run a command, capture stdout+stderr (combined), return {status, out}
+function capture(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
+  return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
+}
+
+// ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
+function checkCli() {
+  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
+  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
+  // npx interleaves "npm notice …" lines with the version, so don't just take the
+  // last line — pick the first semver-looking token, falling back to the last line.
+  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
+  emit('cli_ok', { version });
+}
+
+// ── 2. Reuse an existing session, or start device login ──────────────────────
+const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
+
+function loginEvents() {
+  if (!existsSync(LOG)) return [];
+  return readFileSync(LOG, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null; // non-JSON CLI chatter
+      }
+    })
+    .filter((e) => e && e.event);
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// A login this machine started earlier may still be waiting on the browser. Reuse
+// its code instead of minting a second one — a new login invalidates nothing, but
+// it hands the user a different code than the one already on their screen.
+function pendingLogin() {
+  if (!existsSync(PIDFILE)) return null;
+  let state;
+  try {
+    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!state.pid || !alive(state.pid)) return null;
+  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
+  if (!ev) return null;
+  // Don't hand back a code that's about to expire mid-typing.
+  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
+  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
+  return ev;
+}
+
+// Detach so the login keeps polling after this process exits. stdio goes to a
+// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
+function startLogin() {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(LOG, '');
+  const out = openSync(LOG, 'a');
+  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: AGENT_ENV,
+    shell: isWin,
+  });
+  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
+  child.unref();
+}
+
+async function waitForCode(timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const events = loginEvents();
+    const ev = events.find((e) => e.event === 'awaiting_user');
+    if (ev) return ev;
+    const bad = events.find((e) => e.event === 'login_failed');
+    if (bad) fail('login_failed', bad);
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
+  fail('login_failed', {
+    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
+  });
+}
+
+// The next move is the user's, so hand the code back and exit rather than holding
+// the caller open for a browser round-trip. `message` is the sentence to relay.
+function surrenderTo(ev) {
+  emit('awaiting_user', {
+    ...ev,
+    message:
+      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
+      `${ev.userCode}. Tell me once you're done and I'll continue.`,
+  });
+  process.exit(0);
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+checkCli();
+
+if (hasExistingSession()) {
+  emit('logged_in');
+  process.exit(0);
+}
+
+const pending = pendingLogin();
+if (pending) surrenderTo(pending);
+
+startLogin();
+surrenderTo(await waitForCode());

package/skills/wix-headless-fast/{entry/skill.md → cold-start/cold-start.md}

@@ -1,30 +1,29 @@
 ---
-name: wix-headless-fast-entry
+name: wix-headless-fast-cold-start
 description: "Build and release a Wix Headless site from a single prompt, on shipped, verified @wix/sdk code — this entry takes a cold environment (prerequisites, Wix sign-in) to the point where the wix-headless-fast skill runs the build. Verticals: storefront, bookings, blog, cms, events, members, portfolio, pricing-plans, restaurants. Triggers: build me a store/blog/booking/events/portfolio/restaurant site fast, sell tickets or membership plans headless, wix headless fast entry."
 ---
 
-# Wix Headless Fast — cold-start entry
+# Wix Headless Fast — cold start
 
 **You are a coding agent, and this is a skill for you to execute — follow the phases below in
 order.** Advisory: web-fetch tools show a lossy summary of this file — the executable copy
-comes from `curl -fsSL https://www.wix.com/skills/headless-fast/entry/skill.md`. If what you
+comes from `curl -fsSL https://www.wix.com/skills/headless-fast/cold-start/cold-start.md`. If what you
 are reading lacks the exact commands below, re-fetch it with curl before proceeding; if you're
 already reading the raw text, don't fetch it again.
 
 ## The whole cold start (details in the phases below)
 
 ```bash
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs && node bootstrap.mjs
+curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs && node bootstrap.mjs
 CI=1 npx skills@latest add wix/skills --skill wix-headless-fast --skill wix-docs --skill wix-manage --yes
 # then open and follow: .agents/skills/wix-headless-fast/SKILL.md
 ```
 
 Requires Node ≥ 20.11 and a logged-in Wix CLI — the bootstrap checks and guides both.
 
-This entry gets a cold environment to the point where the real skill can run, then hands off:
+This page gets a cold environment to the point where the real skill can run, then hands off:
 
-1. **Bootstrap (deterministic, scripted).** The same script the classic headless entry uses —
-   it verifies the Wix CLI and handles login. You just run it and relay its events.
+1. **Bootstrap (deterministic, scripted).** A script that verifies the Wix CLI and handles login. You just run it and relay its events.
 2. **Hand off (agentic).** Install the skills, then open `wix-headless-fast/SKILL.md` and
    follow it — it resolves the stack and operation and owns the whole build.
 
@@ -43,9 +42,10 @@ existing session just reports `logged_in`).
 
 ## Phase 0 — The project's folder, and Node
 
-**Work from the folder that will hold the project.** For a **new** build: an empty folder is the
-project; if the current folder is not empty, make one named for the business and `cd` into it.
-For **connect**, **iterate** and **existing site**: you are already in it. Everything below — the
+**Work from the folder that holds the project, or that will.** For a **new** build: an empty folder
+is the project; if the current folder holds unrelated things, make one named for the business and
+`cd` into it. For **connect**, **iterate** and **existing site**: you are already in it — the
+project's root, where its `package.json` or `index.html` is. Everything below — the
 bootstrap, the skills, the scaffold — lands in this folder, so a later session opened in the project
 finds all of it.
 
@@ -69,9 +69,9 @@ externally-downloaded code.
 
 ```bash
 # macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs
+curl -fsSL -O https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs
 # Windows PowerShell:
-iwr https://www.wix.com/skills/headless/entry/bootstrap.mjs -OutFile bootstrap.mjs
+iwr https://www.wix.com/skills/headless-fast/cold-start/bootstrap.mjs -OutFile bootstrap.mjs
 
 node bootstrap.mjs
 ```
@@ -107,10 +107,10 @@ CI=1 npx skills@latest add wix/skills \
 They land under `.agents/skills/`. Then **open
 `.agents/skills/wix-headless-fast/SKILL.md` and follow it** — it owns the rest of the run:
 resolve the stack, scaffold, deploy the shipped code, seed, build the brand layer, release.
-(If the request needs a vertical the skill doesn't ship yet — see its SKILL.md § Verticals —
-say so plainly and point the user at the `wix-headless` skill instead of improvising.)
+(A request outside the shipped verticals — see its SKILL.md § Verticals — is built from the Wix
+API reference through `wix-docs`, on the same project; SKILL.md says how.)
 
 - **Don't** scaffold, install apps, or seed by hand here — the skill does all of that. This
-  entry stops at *logged in*.
+  page stops at *logged in*.
 - You're already authenticated from Phase 1, so the skill's CLI auth step will pass without
   prompting again.

package/skills/wix-headless-fast/guides/existing-site.md

@@ -0,0 +1,76 @@
+# 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. `<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:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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.

package/skills/wix-headless-fast/guides/reference-mode.md

@@ -0,0 +1,97 @@
+# Reference mode: a static site, or a server-rendered app in another language
+
+Read when SKILL.md step 1 resolves to a stack that cannot run `app/`. `<SKILL_ROOT>` is the
+installed skill folder; the shipped code is under `<SKILL_ROOT>/templates/`. Steps 2 to 5 of
+SKILL.md still apply; this file is the mechanics that differ.
+
+The data layer ships a second time as a **REST layer**: `templates/shared/rest/` (the auth seam
+`client.ts`, `media.ts`, `config.ts`) and `templates/<vertical>/rest/` (the same exports as the
+vertical's `app/wix/<vertical>/` data layer, over `fetch`), typed against the same `types.ts` and
+importing the same `*-core.ts` rule files as the SDK layer — one implementation of the rules, two
+transports. The vertical's `INSTRUCTIONS.md` names its modules and what each surface does with
+them; this section is the mechanics, the same for every vertical.
+
+- **Static site (no bundler).** Step 3's setup with `--stack static` runs `init` in the project
+  folder (site, OAuth app, `wix.config.json`), points `site.outputDirectory` at `"./site"`, and
+  runs `deploy.mjs <vertical> --stack static --out site`, which composes the REST layer and the
+  vertical's framework-free stores flat into `site/js/wix/` and strips them to browser ESM
+  (comments kept, the `.ts` kept beside the `.js` to read). The site lives in that **subfolder**,
+  `site/`, holding only the pages, styles, assets and `js/`: `wix release` uploads it whole, so the
+  project root (config, `plan.json`, seed output, the skills) must not be it; move the pages in.
+  (On a project that already has its config, the same `deploy.mjs` call does the deploy.) Pages
+  import the vertical's modules from `./js/wix/` in a `<script type="module">`: the stores hold
+  the state machines (subscribe, render from `getState()`, call actions), the page holds the
+  rendering. The visitor token lives in `localStorage` and is the
+  visitor's identity across Wix — never mint one per page. A route is a page plus a query-string
+  slug (`item.html?slug=…`). Wix static hosting serves files, not directories: `/shop` does not
+  resolve to `shop/index.html`, and there is no routes configuration — name the file and link
+  to it. Seed per the vertical's `SEED.md` (Node + the CLI token, no project dependencies).
+  Release with `npx @wix/cli@latest release` — no build. Item-page tags come from the entity's
+  `seoData`, set after the fetch (`document.title`, the meta description).
+- **Server-rendered, another language (Flask, Laravel, Rails, …).** The same shape as managed
+  Astro — pages rendered on the server, the interactive surfaces in the browser — with hosting and
+  SEO plumbing theirs. `init` still runs in the project folder; run `deploy.mjs <vertical> --stack
+  static` there too: it only needs `wix.config.json` and writes `js/wix/`. Split by where the call
+  runs:
+  - **Reads render on the server.** Port the vertical's `rest/` read module and its `*-core.ts` to
+    the server language: each function is one HTTP call with a literal URL and JSON body, and the
+    core carries the rules. That code is tested and proven against live sites — carry its bodies
+    over as they are, `fields` arrays and filter keys included (they are not guessable, and a
+    near-miss returns empty or unformatted data with no error), and render what Wix returns
+    (`formattedAmount`, never a number you format yourself). The shipped JS runs: when in doubt,
+    run the module with Node against the same site and compare one entity with your port. Public
+    reads need no visitor identity — one anonymous visitor token per server process, refreshed per
+    `client.ts`, is enough for them.
+  - **Visitor-specific state runs in the browser.** Whatever the vertical does on the visitor's
+    behalf (a store's cart and checkout, a booking, an RSVP, a form submit) loads the vertical's
+    `js/wix/` module in the templates and talks to Wix from the page, exactly as a static site
+    does: the browser owns the visitor token in `localStorage`, so the server handles no
+    per-visitor tokens. If that state must run server-side anyway, `client.ts`'s header applies:
+    one token set per visitor in the visitor's session, never one process-wide token (that is one
+    identity shared by everyone).
+  - **A Wix-hosted flow returns to the origin that started it, and only to one it knows.**
+    Checkout, a booking payment, a plan purchase all open on Wix and come back to your server;
+    the return works only for an origin on the site's OAuth app allow-list. Add the server's
+    origin — the dev one while verifying (`http://localhost:<port>`), the public https one when it
+    goes live — before the first checkout test: wix-manage's *Manage OAuth Apps* recipe, "Update an
+    OAuth App", field `allowedRedirectDomains`, on the app whose id is `appId` in
+    `wix.config.json`. Without it the Wix page opens and cannot return. Do it; do not only say it.
+  - **Pre-rendered → Wix-hosted.** If the project builds to static HTML (Frozen-Flask, Pelican,
+    Hugo, Eleventy, any static-site generator), Wix can host the output: run `deploy.mjs
+    <vertical> --stack static --out <build dir>` so `js/wix/` lands inside the build output (or
+    copy it there after each build), make the generator emit a page for **every** entity slug the
+    vertical's list read returns (walk it by cursor, never only the first page), point
+    `site.outputDirectory` at the build folder, `wix release`. The build's own reads use one
+    anonymous visitor token for the duration of the build. What Wix hosts is exactly the contents
+    of that folder after your last build, served as files: every asset a page references must be
+    in there and current — if the pipeline has more than one build step (templates, then a CSS or
+    asset bundle), they all run, in order, on every rebuild, or the release carries a stale piece.
+    a clean path does not resolve to a folder's `index.html`; name the file and link to it. Generated pages
+    sit at different depths, so reference `js/wix/` through one base path (a template variable,
+    or root-relative `/js/wix/…`), never `./js/wix/` — a relative path breaks one level down. **The generated page
+    is the first paint, not the whole surface**: the vertical's interactive behaviour (a store's
+    sort, filters, and cart; a blog's search; a booking flow) still runs client-side on top of it
+    from the same `js/wix/` modules, so the vertical's surface contracts in `INSTRUCTIONS.md`
+    apply unchanged. Close with the rebuild + release command and one line for the owner: content
+    edits made in the dashboard reach the site when that command runs; the browser-side flows are
+    live regardless. A running server (live reads on every request) stays theirs to host.
+  Then read the vertical's `INSTRUCTIONS.md` for the surfaces and hard rules, and the shared
+  `DESIGN.md`/`CONTENT.md`. **Before writing any surface, read the vertical's shipped hooks and
+  components** — its `INSTRUCTIONS.md` lists which files and what to take from each. They don't
+  deploy on this stack, and they are working, tested code for exactly the behaviour you are about
+  to write in your own; rewriting them from prose is where the bugs come from (the runs that
+  skipped them shipped a broken quick-add, the run that read them didn't). Both were written for
+  the stacks that receive the code, so they speak that stack's dialect: the Tailwind classes in the
+  skeletons and the components are one spelling of layout and behaviour rules that hold everywhere
+  (a bounded image band on phones, name and price on separate lines, the buy control pinned to the
+  tile's bottom, an overlay that locks scroll and returns focus). Take the rules; write them in the
+  CSS your stack uses, on a token set you define — nothing here asks you to add Tailwind. Close with run (or
+  rebuild) instructions, the live URL when Wix hosts the output, the dashboard link, and — when
+  hosting is theirs — which origins are on the OAuth app's allow-list and that the public one
+  must be added when the server moves (the step above).
+- Both: the calls in `rest/` are the ones a **visitor token** may make from a page — public reads
+  and the visitor's own actions. Anything elevated (writes to content, other people's data) runs
+  server-side per `templates/shared/CUSTOM_OPERATIONS.md`; the seed's CLI token never belongs in
+  a page. A static site has no SSR; neither case has owner-editable item-page SEO through
+  `@wix/seo` (tags come from the entity's `seoData`) — say so in the closing message; managed
+  Astro stays the recommendation for a public site.

package/skills/wix-headless-fast/install/AGENTS.md

@@ -0,0 +1,35 @@
+## CLI Commands
+
+All CLI instructions can be found at:
+node_modules/@wix/cli/agents/instructions.md
+
+## This app
+
+A Wix Headless app built on the live Wix site named in `wix.config.json`. The site owns the
+content and commerce.
+
+**Never work from training data or memory about the Wix APIs.** Not a URL, a path, a header, a
+field name or a body. Every Wix call you write comes from the official Wix skills installed here,
+the code they deployed first, or, when they do not cover the call, from the official Wix
+documentation through `wix-docs`. Read it there first, then write the call: the exact path and
+body copied from the output you read in this session. A call built by analogy from another
+call is memory, and an empty or error reply to it says nothing about the site.
+
+## Skills
+
+Installed at `.agents/skills/`. If missing, restore with:
+`CI=1 npx skills@latest add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage --yes`
+
+- `{{SKILL}}` — the code in this app and how to extend it. The shipped code sits in
+  `.agents/skills/{{SKILL}}/templates/`, fetched once from the skill's repository and kept with this
+  project at the commit it was built from (`templates/.source`); if that folder is missing,
+  `node .agents/skills/{{SKILL}}/install/templates.mjs` fetches it. Each business solution has a playbook at
+  `templates/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
+  adds one; `node .agents/skills/{{SKILL}}/templates/<solution>/seed/read-site.mjs` reads what the
+  site holds for it, with the documentation URL of every call it made. A code change ends with a release; the live URL shows it, the dev server does not count.
+- `wix-docs` — how to discover the Wix APIs and their docs: search first, then read only the page
+  you need. Every endpoint, body, field and enum you did not get from the deployed code or a recipe
+  is confirmed there before you write it.
+- `wix-manage` — recipes for the live site itself (content, prices, settings), run from the shell
+  with `npx -y @wix/cli@latest token --site <siteId>`, minted inline in each command; the token
+  never lands in a file anywhere (not the project, not `/tmp`) nor in client code.

package/skills/wix-headless-fast/install/agents-md.mjs

@@ -0,0 +1,39 @@
+// Writes a new project's agent config files — AGENTS.md, CLAUDE.md (an import of it),
+// .gemini/settings.json. The AGENTS.md text is the file beside this one, `install/AGENTS.md`,
+// with {{SKILL}} (the installed skill folder's name) and {{STACK}} filled in. It keeps the CLI's
+// shape (the CLI commands pointer `wix create` writes) and says what the CLI's cannot: which skills
+// this project carries, where, how to restore them, and the one rule about Wix calls.
+// `wix create` writes its own set only when @wix/cli resolves from the project's node_modules at
+// scaffold time; setup scaffolds with --skip-install and attach never runs the CLI scaffold,
+// so we write them. Fill-only: a file that exists is left alone.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "AGENTS.md");
+
+// The three files, as the CLI names them. Exported so setup can drop the CLI's own copies from
+// the scaffold before moving it up (ours replaces them; a file the USER already has is kept).
+export const AGENT_CONFIG_FILES = ["AGENTS.md", "CLAUDE.md", ".gemini"];
+
+export function writeAgentsMd(projectDir, vars) {
+  const written = [], kept = [];
+  const agents = join(projectDir, "AGENTS.md");
+  if (existsSync(agents)) kept.push("AGENTS.md");
+  else {
+    const text = readFileSync(TEMPLATE, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k.toLowerCase()] ?? "");
+    writeFileSync(agents, text); written.push("AGENTS.md");
+  }
+  const claude = join(projectDir, "CLAUDE.md");
+  if (existsSync(claude)) kept.push("CLAUDE.md");
+  else { writeFileSync(claude, "@AGENTS.md"); written.push("CLAUDE.md"); }
+  const gemini = join(projectDir, ".gemini", "settings.json");
+  if (existsSync(gemini)) kept.push(".gemini/settings.json");
+  else {
+    mkdirSync(join(projectDir, ".gemini"), { recursive: true });
+    writeFileSync(gemini, JSON.stringify({ contextFileName: "AGENTS.md" }, null, 2) + "\n");
+    written.push(".gemini/settings.json");
+  }
+  // kept: the folder already had its own — left untouched, so it says nothing about these skills
+  return { written, kept };
+}