@wix/agent-skills 1.19.0 → 1.19.2

package/skills/wix-headless/references/inline-recipes/how-to-code-members-astro.md

@@ -1,6 +1,6 @@
 ---
 name: "How to Code Members (Astro)"
-description: The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend.
+description: "The frontend contract for member sign-up / log-in / log-out and member-gated surfaces on a Wix-managed **Astro** frontend — the built-in `/api/auth/login` + `/api/auth/logout` routes that `@wix/astro` ships, the `returnToUrl` param, gating a page by resolving the member in SSR / a backend route, reading the current member with `@wix/members` `getCurrentMember`, and the two rules that keep this path from breaking: **no `OAuthStrategy`/no client** (that 500s under auto-auth) and **no `auth.elevate`** for a member reading their own data. Specifies the *how* for the Astro axis only — read `how-to-code-members-non-astro.md` for any non-Astro frontend."
 ---
 **RECIPE**: How to Code Member Auth on a Wix-managed **Astro** Frontend (built-in `/api/auth/*`, `@wix/members`)
 

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/references/managed/CREATE.md

@@ -107,6 +107,11 @@ headlines, kickers, subtitles, and CTA labels per **`references/CONTENT.md`**
 Either way, `CONTENT.md` §1 (the business's category must read literally above the fold) always holds —
 a page a first-time visitor can't identify isn't done yet, regardless of voice.
 
+**If a loaded vertical ships an experience overlay** — `references/inline-recipes/experience-<vertical>.md`
+(today: `experience-store.md`) — read it after `DESIGN.md`/`CONTENT.md`. It carries that vertical's own
+design and copy bar (what its surfaces must show, how to derive the direction from its content); the
+general files stay the floor.
+
 Then build the pages the user's intent calls for, **wired to the live backend**, using
 **`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
 bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the

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