@wix/agent-skills 1.18.2 → 1.19.1

package/skills/wix-headless/entry/bootstrap.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import readline from 'node:readline';
+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 = {}) =>
@@ -24,6 +26,12 @@ const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no
 // 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-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-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 });
@@ -41,60 +49,108 @@ function checkCli() {
 }
 
 // ── 2. Reuse an existing session, or start device login ──────────────────────
-function hasExistingSession() {
-  const r = capture(WIX[0], [...WIX.slice(1), 'whoami']);
-  if (r.status !== 0) return false;
-  emit('logged_in');
-  return true;
-}
+const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
 
-function login() {
-  return new Promise((resolve) => {
-    const child = spawn(WIX[0], [...WIX.slice(1), 'login'], { shell: isWin, env: AGENT_ENV });
-    const rl = readline.createInterface({ input: child.stdout });
-    let loggedIn = false;
-    // Buffer the CLI's own diagnostics (stderr + any non-event stdout chatter) so a
-    // failure reports the REAL cause — network/proxy error, expired code, etc. — not
-    // a guess. Keep only the tail so a chatty CLI can't blow up memory, and draining
-    // stderr also avoids the pipe filling up and stalling the child.
-    let diag = '';
-    const collect = (chunk) => {
-      diag = (diag + chunk).slice(-2000);
-    };
-    child.stderr?.on('data', collect);
-    rl.on('line', (line) => {
-      const t = line.trim();
-      if (!t) return;
-      // In agent mode the CLI emits {event:"awaiting_user"|"success"|"logged_in", ...}
-      // — pass those straight through so the agent can relay the device code.
+function loginEvents() {
+  if (!existsSync(LOG)) return [];
+  return readFileSync(LOG, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
       try {
-        const ev = JSON.parse(t);
-        if (ev && ev.event) {
-          process.stdout.write(t + '\n');
-          if (ev.event === 'success' || ev.event === 'logged_in') {
-            loggedIn = true;
-            resolve();
-          }
-          return;
-        }
-        collect(line + '\n'); // JSON, but not an event — keep for diagnostics
+        return JSON.parse(l);
       } catch {
-        collect(line + '\n');
-      } // non-JSON CLI chatter — keep for diagnostics
-    });
-    // Only a success/logged_in event counts as login. On any other exit, surface the
-    // CLI's actual output — do NOT assume a cause (agent mode, etc.).
-    child.on('close', (code) => {
-      if (loggedIn) return;
-      const detail =
-        diag.trim().slice(-1500) ||
-        `wix login exited (code ${code}) before authenticating, with no output.`;
-      fail('login_failed', { code, detail });
-    });
-    child.on('error', (e) => fail('login_failed', { detail: String(e) }));
+        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()) await login();
+
+if (hasExistingSession()) {
+  emit('logged_in');
+  process.exit(0);
+}
+
+const pending = pendingLogin();
+if (pending) surrenderTo(pending);
+
+startLogin();
+surrenderTo(await waitForCode());

package/skills/wix-headless/entry/skill.md

@@ -36,9 +36,9 @@ If that errors (Node not installed) or prints a version below 20.11, install or
 
 ## Phase 1 — Run the bootstrap (deterministic)
 
-Download the bootstrap script, then run it. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it as a background/streaming process and relay its events to the user.**
+Download the bootstrap script, then run it — an ordinary foreground command that exits on its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it and relay its events to the user.**
 
-The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, no filesystem writes. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
+The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, and the only files it writes are the login's own output and pid under the OS temp dir. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
 
 ```bash
 # macOS/Linux:
@@ -56,10 +56,12 @@ The script emits one JSON object per line:
 | Event | What to do |
 |---|---|
 | `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`) | Show the URL and code in plain prose; wait for the user to finish the login in their browser. |
+| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
 | `logged_in` / `success` | Login done — continue. |
 | `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
 
+On `awaiting_user`, run the script again once the user says they've logged in: it reports `logged_in` and you continue. Re-running while they're still in the browser is harmless — it returns the same code rather than issuing a new one.
+
 ## Phase 2 — Install the skill and hand off
 
 Install the Wix Headless skills (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI command):

package/skills/wix-headless/references/managed/AUTHENTICATION.md

@@ -13,12 +13,32 @@ Never emit them to stdout, stderr, logs, prompts, or tool results.
 npx @wix/cli@latest whoami   # exits 0 when logged in; non-zero when logged out
 ```
 
-If it's non-zero, **log in yourself** — don't punt to the user and stop:
+If it's non-zero, **log in yourself** — don't punt to the user and stop. A foreground command that exits in seconds, one JSON event per line:
 
-1. Run `npx @wix/cli@latest login` with **`run_in_background: true`** (no shell `&`, no redirect of your own — the harness captures stdout to its task-output file and returns the path).
-2. Poll that file for the first JSON event: `{"event":"awaiting_user","userCode":"…","verificationUri":"…"}`.
-3. Surface it to the user in plain prose: *"Open `<verificationUri>` and enter the code `<userCode>` — I'll continue once you've logged in."* **Send the message; do not re-invoke login.**
-4. Wait for the harness `task-notification` with `<status>completed</status>` (not a sleep loop). On exit 0, run `whoami` once to confirm, then proceed.
+```bash
+node ../../entry/bootstrap.mjs   # path relative to this file
+```
+
+| Event | Do |
+|---|---|
+| `logged_in` | Session exists — continue. |
+| `awaiting_user` (`verificationUri`, `userCode`, `message`) | Send `message` verbatim, then stop. Re-run the script when the user says they're done → `logged_in`. Re-running early returns the **same** code, not a new one. |
+| `cli_unreachable` / `login_failed` (`detail`) | Show `detail` and stop. |
+
+### If you'd rather not execute it
+
+Read `../../entry/bootstrap.mjs` and do the same thing yourself. What matters:
+
+```bash
+# AI_AGENT must be set, or the CLI renders an interactive Ink TUI and emits no JSON.
+# Detach, redirecting to a FILE — a pipe dies with your process and the CLI gets EPIPE.
+AI_AGENT=my-agent nohup npx -y @wix/cli@latest login > /tmp/wix-login.log 2>&1 &
+
+grep -m1 awaiting_user /tmp/wix-login.log
+# {"event":"awaiting_user","expiresInSeconds":600,"userCode":"…","verificationUri":"…"}
+```
+
+Send the user that URL + code, then stop — nothing moves until they act. The detached login lands the session on its own; resume with `whoami` (exit 0). Codes last ~10 min; after that, start a new login and surface the new code.
 
 ## 2 · Mint the token
 

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

@@ -11,6 +11,11 @@ layer, hooks, components, pages, and a seed script that are already correct —
 job narrows to brand, layout, copy, and wiring. The decisions live in the code; don't
 re-litigate them.
 
+**Scope.** This is the bootstrap, tuned for Wix-managed Astro, and each vertical ships *one*
+shape of its solution. Deploy it as-is when the brief doesn't contradict it. When the brief
+asks for something that shape doesn't express — or once the site exists and the work turns to
+managing or extending it — that's `wix-docs` and `wix-manage`, not a workaround here.
+
 ## Relationship to sibling skills
 
 | Skill                        | Use when                                                                                                               |
@@ -36,13 +41,14 @@ re-litigate them.
   this — nothing to wire by hand.
 - **Data as-is; presentation is yours.** The data layer, hooks, and cart chrome are wired
   as-is — never rewrite their internals, re-route them through API routes, or re-derive a
-  request shape. For a genuine gap, first read the relevant official contract with the
-  `wix-docs` skill; do not search generated SDK types, package files, or `node_modules` to
-  infer it. A normal caller-permitted operation belongs in a new data-layer function. A
-  privileged operation belongs in a validated server endpoint — see
-  `references/shared/CUSTOM_OPERATIONS.md`. The presentation components ship only as
-  **references**: the vertical's INSTRUCTIONS names the surfaces you design and implement
-  yourself on the shipped hooks (for storefront: card, grid, shop + PDP surfaces, home).
+  request shape. When the brief needs something they don't express, read the shipped file that
+  owns it and confirm the contract with `wix-docs`; never infer one from generated SDK types,
+  package files, or `node_modules`. A normal caller-permitted operation belongs in a new
+  data-layer function. A privileged operation belongs in a validated server endpoint — see
+  `references/shared/CUSTOM_OPERATIONS.md`. The presentation **doesn't ship**: the vertical's
+  INSTRUCTIONS names the surfaces you design and implement yourself on the shipped hooks,
+  with a skeleton carrying each surface's contract (for storefront: the shop and PDP pages
+  with their islands, and home).
 - **Never mock, fail loudly, purchases via Wix.** Live data or an honest empty state; surfaced
   errors, not swallowed ones; checkout/purchase always through the Wix redirect session.
 - **Optional capabilities are deployed from the plan.** A vertical can opt into a shared
@@ -70,6 +76,17 @@ re-litigate them.
    `--vertical` is required and picks which shipped code deploys AND which seed runs — use
    the vertical you resolved from the Verticals table.
 
+   fast-path scaffolds with `--skip-git`: it composes its own steps and leaves version control to
+   you / the enclosing repo, so it does **not** create the scaffold's usual git repo + initial
+   commit (which would otherwise become a nested-repo gitlink if the project lands inside a repo).
+
+   Optional `--flatten`: by default the project is created in a **new subfolder** (named after the
+   business). Pass `--flatten` to create it **directly in the current directory** instead — a plain
+   move of the scaffold's files up into the CWD, done **before** the dependency install starts so
+   nothing is half-moved (and since git was skipped, there's no nested repo to reconcile). Use it
+   when bootstrapping into an existing repo that must stay a single flat tree; otherwise omit it
+   and keep the subfolder.
+
    It emits one JSON event per line and returns in **~35s**: **scaffolds** the project,
    **deploys** the shipped code (patching `package.json` with every dependency the code
    imports, and placing the pre-resolved lockfile), then **starts two detached background
@@ -156,6 +173,7 @@ references/<vertical>/
   app-astro/           # Astro overlay importing ONLY from the core:
     pages/…            #   SSR fetch → DTO props → client:load islands; item pages carry
                        #   wixMetadata + <SEO.Tags>; chrome islands are client:only
+                       #   (storefront ships no pages — its INSTRUCTIONS carries their skeletons)
     layouts/…          #   (reuse SiteLayout when it fits)
   seed/                # seed-<vertical>.mjs (REST, mints its own CLI token) + SEED.md
 ```

package/skills/wix-headless-fast/entry/skill.md

@@ -15,7 +15,7 @@ already reading the raw text, don't fetch it again.
 
 ```bash
 curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs && node bootstrap.mjs
-CI=1 npx skills@latest add wix/skills/skills/wix-headless-fast --yes
+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
 ```
 
@@ -50,15 +50,14 @@ version, install or upgrade Node first — do **not** work around it:
 
 ## Phase 1 — Run the bootstrap (deterministic, shared)
 
-Download and run the shared bootstrap script. It verifies the Wix CLI and handles login,
-emitting **one JSON event per line** on stdout. **Run it and relay its events** — it exits on
-its own once the CLI is verified and a session exists (seconds, when already logged in). Only
-when a login is actually needed does it pause on `awaiting_user`; surface the URL + code and
-let it keep running until the login completes.
+Download and run the shared bootstrap script — an ordinary foreground command that exits on
+its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event
+per line** on stdout. **Run it and relay its events.**
 
 The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives
-`wix login` (a device-code flow) — no other network calls, no filesystem writes. Read it first
-if your sandbox flags externally-downloaded code.
+`wix login` (a device-code flow) — no other network calls, and the only files it writes are
+the login's own output and pid under the OS temp dir. Read it first if your sandbox flags
+externally-downloaded code.
 
 ```bash
 # macOS/Linux:
@@ -74,20 +73,30 @@ node bootstrap.mjs
 | Event | What to do |
 |---|---|
 | `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`) | Show the URL and code in plain prose; wait for the user to finish the login in their browser. |
+| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
 | `logged_in` / `success` | Login done — continue. |
 | `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
 
-## Phase 2 — Install the skill and hand off
+On `awaiting_user`, run the script again once the user says they've logged in: it reports
+`logged_in` and you continue. Re-running while they're still in the browser is harmless — it
+returns the same code rather than issuing a new one.
 
-Install the skill (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI
-command):
+## Phase 2 — Install the skills and hand off
+
+Install the skill and its two companions (`CI=1` forces plain non-interactive CLI output —
+keep it on every Wix CLI command). Repeat `--skill` per skill; a comma-separated list is not
+parsed:
 
 ```bash
-CI=1 npx skills@latest add wix/skills/skills/wix-headless-fast --yes
+CI=1 npx skills@latest add wix/skills \
+  --skill wix-headless-fast --skill wix-docs --skill wix-manage --yes
 ```
 
-It lands at `.agents/skills/wix-headless-fast/`. Then **open
+- **`wix-headless-fast`** — the build itself.
+- **`wix-docs`** — the API reference the playbooks defer to for any contract they don't cover.
+- **`wix-manage`** — management recipes, for admin work on the site after it exists.
+
+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 —

package/skills/wix-headless-fast/install/fast-path.mjs

@@ -4,15 +4,18 @@
 // or for connect/iterate runs (which must NOT scaffold and don't use this script).
 //
 //   node <SKILL_ROOT>/install/fast-path.mjs --business-name "<Brand>" --plan plan.json \
-//        --vertical <storefront|bookings|…> [--stack astro] [--folder-name <npm-safe-name>]
+//        --vertical <storefront|bookings|…> [--stack astro] [--folder-name <npm-safe-name>] [--flatten]
+//
+// --flatten (opt-in): leave the project directly in the current directory instead of a subfolder,
+// moving it before the background install starts. Default off — the normal output is a subfolder.
 //
 // It emits ONE JSON event per line and exits in ~35s with BOTH long steps — the dependency
 // install AND the seed — running detached in the background (logs + completion markers
 // reported in the final event), so the caller can build the brand layer while they finish.
 // Steps: scaffold (Wix CLI; requires a logged-in session) → deploy shipped code + deps +
-// lockfile → start `npm ci || npm install` detached → start the seed detached.
+// lockfile → pin AGENTS.md → start `npm ci || npm install` detached → start the seed detached.
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -34,6 +37,8 @@ const businessName = flag("business-name");
 const planPath = flag("plan");
 const vertical = flag("vertical");
 const stack = flag("stack") ?? "astro";
+// Opt-in: leave the project in the current directory (flat) instead of a subfolder.
+const flatten = argv.includes("--flatten");
 // --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong
 // seed against the plan — fail loudly with the discovered choices instead.
 const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
@@ -51,7 +56,10 @@ const plan = JSON.parse(readFileSync(planPath, "utf8"));
 const folderName =
   flag("folder-name") ??
   businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
-const projectDir = resolve(process.cwd(), folderName);
+// `let`: after deploy we flatten the scaffold up into the repo root and repoint
+// projectDir there, so the detached install/seed and every reported path use the
+// final location.
+let projectDir = resolve(process.cwd(), folderName);
 
 // ---- 1 · scaffold -------------------------------------------------------------------------------
 if (existsSync(join(process.cwd(), "wix.config.json"))) {
@@ -63,9 +71,14 @@ if (existsSync(join(projectDir, "wix.config.json"))) {
   emit("scaffolding", { folder: folderName });
   const scaffold = spawnSync(
     "npm",
+    // --skip-git: this wrapper composes its own steps and leaves version control to
+    // the caller / the enclosing repo; the scaffold's own `git init` + "Initial
+    // commit" is noise here, and becomes a nested-repo (submodule gitlink) hazard
+    // if the project is later placed inside an existing repo. --skip-install for the
+    // same reason: deps install in a detached step below.
     ["create", "@wix/new@latest", "--", "headless",
      "--folder-name", folderName, "--business-name", businessName,
-     "--site-template", "--skip-install", "--no-publish"],
+     "--site-template", "--skip-install", "--skip-git", "--no-publish"],
     { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
   );
   if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
@@ -95,6 +108,36 @@ try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going with raw
 if (deployResult.error) fail("deploy", deployResult.error);
 emit("deployed", deployResult);
 
+// ---- 2b · record what this project is, for later sessions ---------------------------------------
+const pin = spawnSync(
+  "node",
+  [join(SKILL_ROOT, "install", "pin-agents-md.mjs"), "--vertical", vertical, "--stack", stack],
+  { cwd: projectDir, encoding: "utf8", timeout: 10_000 },
+);
+try { emit("agents_md", JSON.parse(pin.stdout)); } catch { /* never block the build on the note */ }
+
+// ---- 2c · optional --flatten: move the scaffold into the current directory ----------------------
+// OFF by default — the normal output is a self-contained subfolder, unchanged. Opt in when the
+// caller wants the project directly in the current directory (e.g. bootstrapping into an existing
+// repo that must stay one flat tree). Done HERE, before the detached install below, on purpose:
+// no node_modules exists yet, so the move is instant and cannot collide with a running install —
+// the failure mode when a project is flattened by hand after the background install has started.
+// A pure move: the scaffold was created with --skip-git (above), so there is no nested repo to
+// reconcile — git is whatever the destination already is.
+const targetDir = process.cwd();
+if (flatten && projectDir !== targetDir) {
+  try {
+    for (const entry of readdirSync(projectDir)) {
+      renameSync(join(projectDir, entry), join(targetDir, entry));
+    }
+    rmSync(projectDir, { recursive: true, force: true });
+    projectDir = targetDir;
+    emit("flattened", { into: targetDir });
+  } catch (e) {
+    fail("flatten", e?.stack || e);
+  }
+}
+
 // ---- 3 · start the dependency install, detached --------------------------------------------------
 const installLog = join(projectDir, "npm-install.log");
 const logFd = openSync(installLog, "a");

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

@@ -0,0 +1,57 @@
+// Record what this project is in its agent instruction files, so a later session — which has
+// none of the build conversation and may never open SKILL.md — still knows the Wix site is the
+// source of truth and which skill answers which kind of question.
+//
+//   node <SKILL_ROOT>/install/pin-agents-md.mjs --vertical <name> [--stack astro]
+//
+// Run from the project root. Kept out of deploy.mjs on purpose: "copy a vertical's files" and
+// "record the project's ground rules" are separate concerns with separate reasons to change.
+// APPENDS to each file — a template's or the user's own content is never overwritten — and is
+// idempotent via the heading sentinel, so re-running fast-path.mjs writes at most once.
+// Project facts that live in the repo (site id, app id) are NOT copied here; they would go
+// stale against wix.config.json, which is the one place that owns them.
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const argv = process.argv.slice(2);
+const flag = (n, d) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : d; };
+
+const vertical = flag("vertical");
+const stack = flag("stack", "astro");
+// "astro" means the Wix-managed flavour (ambient auth), which is worth naming. Any other stack
+// is echoed as given rather than mapped, so adding one can't silently mislabel the project.
+const frontend = stack === "astro" ? "Wix-managed Astro" : stack.charAt(0).toUpperCase() + stack.slice(1);
+
+const SENTINEL = "## This app — a Wix Headless frontend";
+const note = `
+${SENTINEL}
+
+A ${frontend} frontend for a live Wix site; \`wix.config.json\` identifies the site. Built on
+the **${vertical}** Wix business solution — more can be added to this same app. **The Wix site
+owns the content and commerce** — read and write it through the Wix APIs, never hardcode what
+it holds.
+
+The Wix skills are installed at \`.agents/skills/\` — read them from that exact path:
+
+- **\`wix-headless-fast\`** — the code already deployed in \`src/\` and how to extend it. Every
+  business solution it ships sits under \`references/<solution>/\`: \`INSTRUCTIONS.md\` is that
+  solution's playbook, \`seed/\` creates its content. To add one to this app, run from the
+  project root:
+  \`node .agents/skills/wix-headless-fast/install/deploy.mjs <solution> --stack ${stack}\`
+- **\`wix-docs\`** — the Wix API reference. Confirm any endpoint, request shape, field, or enum
+  here before writing code against it, frontend or backend. Never infer a contract from
+  generated SDK types or \`node_modules\`.
+- **\`wix-manage\`** — recipes for managing the live site itself, as opposed to changing this
+  codebase. No recipe for the task? Fall back to \`wix-docs\`.
+`;
+
+// Both files, independently — a project may have either, both, or neither, and agents differ
+// in which one they read.
+const pinned = ["AGENTS.md", "CLAUDE.md"].map((name) => {
+  const file = join(process.cwd(), name);
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const wrote = !existing.includes(SENTINEL);
+  if (wrote) appendFileSync(file, (existing && !existing.endsWith("\n") ? "\n" : "") + note);
+  return { file: name, wrote, created: wrote && !existing };
+});
+console.log(JSON.stringify({ event: "agents_md", pinned }));

package/skills/wix-headless-fast/references/shared/CUSTOM_OPERATIONS.md

@@ -17,9 +17,9 @@ custom business write, or a third-party service.
 
 ## The research rule
 
-Read the relevant shipped playbook first. For a genuine gap, use `wix-docs` to read the
-official method or feature guide, then implement that contract. One documentation lookup and
-one type check are enough before coding. Investigate further only after a concrete error.
+Read the relevant shipped playbook first. For anything it doesn't cover, use `wix-docs` to
+read the official method or feature guide, then implement that contract. One documentation
+lookup and one type check are enough before coding. Investigate further only after a concrete error.
 
 ## User-created public content