@wix/agent-skills 1.6.0 → 1.8.0

package/skills/wix-headless/references/SETUP.md

@@ -1,304 +1,129 @@
 # Setup
 
-Runs once per session, immediately after plan approval. Establishes MCP connectivity, installs apps, pulls env, kicks off npm install in background, writes memory, creates the user-facing roadmap.
+Runs once after approval, with the contract in scratch. Domain: install the apps the loaded packs declare, pull the Wix env, run `npm install`, and read `siteId` + `appId` from `wix.config.json` into scratch. Run flow (timing, handles, waits, batching) is owned by the framework conductor (`BUILD-astro.md` / `BUILD-own-build.md`; Setup is an early run-step in each).
 
-Target: **~15 seconds on the critical path** (everything after the MCP prefix discovery in Step 0 runs as a single concurrent batch).
-
-This article covers **two entry paths**:
-
-1. **New project flow** (the default — Sections "Step 0", "Setup Dispatch", "npm install recovery"). The orchestrator scaffolds a fresh Astro project via `scaffold.sh` in Discovery Step 1, then runs the dispatch below.
-2. **Existing project flow** (see "Existing project flow" at the bottom). The user already has a working frontend (e.g. a Claude Design output, a hand-coded HTML/JSX site) and wants to **connect it** to Wix Headless to get hosting + Business Solutions. No scaffold, no Astro, no design/seed/pages waves — just connect, install needed apps, optionally wire SDK calls, release.
-
-Both paths share **Step 0 (MCP bootstrap)**. Branch immediately after.
-
-> **Routing decision (do this BEFORE Step 0's dispatch).** Inspect the working directory:
-> - **Empty / non-existent / freshly-scaffolded** AND Discovery Step 1's `scaffold.sh` is what populated it → **New project flow** (continue with this article top-to-bottom).
-> - **Already contains source files** (`index.html`, `*.jsx`, `*.tsx`, `*.vue`, `package.json` from a non-Wix template, etc.) AND no scaffold was dispatched in Discovery → **Existing project flow** (jump to "Existing project flow" at the bottom; skip the Setup Dispatch).
-> - **Contains `wix.config.json`** AND an Astro project structure (`src/`, `astro.config.mjs`) → resume a prior wix-headless run (see `SKILL.md` § "When NOT to Use This Skill" — ask the user "continue or start fresh?").
-> - **Contains `wix.config.json`** AND a non-Astro frontend (`index.html` at root, `*.jsx` files) → already-`init`'d existing project; jump to "Existing project flow" § "After init" (skip the init step itself).
+This article is the **astro entry path** (`frontendBuild === "wix"`): Steps 1–5 + npm recovery. The `none`/`own` classes reuse **only** Step 4a (app installs); their skips (no `env pull`, no `scaffold.sh`, no per-pack `npm install`, no `seed-utilities.sh`) and their `init` bootstrap are owned by `BUILD-own-build.md`. Assumes `DISCOVERY.md`'s CLI-auth pre-flight passed. Routing: `PLAN.md` § "Operation routing" + `BUILD.md`.
 
 ---
 
-## Step 0 — MCP Prefix Discovery + Schema Bootstrap (first time only)
+## Step 1 — Read the scaffolded project config (siteId + appId)
 
-Runs once per session, before any MCP call. Separate from the Setup step because it requires a sequential **discover prefix → verify connectivity → bootstrap schemas** chain.
+> **Single folder — CWD == project == site-root.** `scaffold.sh` flattens the project into CWD: one folder, one `.wix/` (`package.json`, `src/`, `wix.config.json`, `.wix/design-tokens.css`, …), with the end-of-run `AGENTS.md` at its root. Never `cd` into a subdir or look in a parent for `.wix`. `<site-root>` == `<project-dir>` == CWD; pass absolute paths only when a call runs in its own subshell.
 
-1. **Discover the MCP prefix.** Wix MCP tool names take the form `<prefix>WixREADME`. Use whatever tool-discovery primitive your runtime provides to look up `WixREADME` and strip the trailing suffix from the returned tool name — the remainder (ending in `wix-mcp-remote__` or similar) is the **MCP prefix**.
-2. Call `<prefix>WixREADME` once to verify connectivity.
-3. If discovery returns no match or the verify call fails → stop and tell the user: *"Wix MCP tools are not available in this session. Please ensure the Wix MCP server is connected (or that the Wix plugin is enabled), then restart your client."*
-4. **Pre-load Wix MCP tool schemas** — read `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` and follow its single `ToolSearch` invocation. Loads every Wix MCP tool schema the build will use (CallWixSiteAPI, SearchWixRESTDocumentation, ReadFullDocsArticle, ReadFullDocsMethodSchema, SearchWixCLIDocumentation, SearchWixSDKDocumentation, SearchWixHeadlessDocumentation, SearchWixWDSDocumentation, SearchBuildAppsDocumentation, BrowseWixRESTDocsMenu).
-5. Hold the prefix for the whole session. Pass it into **every** subagent prompt as:
-   ```
-   MCP tool prefix: <prefix>
-   Use this prefix for every Wix MCP call. Example: <prefix>CallWixSiteAPI, <prefix>WixREADME.
-   ```
+Do **not** speculatively `Read ./wix.config.json` before the scaffold completes — it doesn't exist yet on a fast-Q&A run, so the read fails and wastes a round-trip.
 
-See `references/shared/MCP_PREFIX.md` for the tool-not-found recovery procedure that subagents use if the prefix somehow fails downstream.
+Once `scaffold_handle` returns, read `./wix.config.json` and hold in scratch:
+- `siteId` — passed as `--site` to `npx @wix/cli@latest token`, embedded in every install body + the `wix-site-id` header on every site-scoped REST call.
+- `appId` — goes into the SDK's `createClient` inputs later.
 
-> **Why the MCP bootstrap is mandatory.** Without it, the first `CallWixSiteAPI` emits `body` as a JSON string (because the schema isn't loaded) and returns `Expected object, received string`. Pinning the schema-load list in `references/commands/mcp-bootstrap.md` and reading it as a discrete step makes the operation impossible to skim past — the orchestrator can skip a footnote; it can't skip a numbered step that resolves to a single concrete tool call.
+Capture CWD as `<site-root>` in scratch. No `cd` step — every file op runs in the project root.
 
 ---
 
-## Setup Dispatch — one concurrent batch
-
-> **BATCHING — read this twice before proceeding.**
->
-> Launch every operation below as a single concurrent batch. No narration, no *"Now setting up:"*, no transition text between dispatches.
->
-> Any text adjacent to a dispatch closes the batch and forces remaining operations into separate turns. An earlier run lost 13s to roadmap-tracker calls splitting across 13 turns; an earlier run lost ~50 minutes to an npm install recovery gate. Both are eliminated by strict single-batch dispatch here.
-
-### Contents of the setup dispatch
-
-The skill assembles this dispatch dynamically from the loaded vertical packs. The items below list what to emit.
-
-#### 1. Verify scaffold completed
-
-**Before the setup dispatch:** read `<project>/wix.config.json` to confirm the background scaffold from Discovery Step 1 finished. If not, wait for the background scaffold to finish. On scaffold failure, retry the inline `npm create @wix/new` call once (same shell command from DISCOVERY.md Step 1); surface the error if it still fails. Recovery ladder is documented in DISCOVERY.md § "Strict-then-recover" — auth, invalid template, etc.
+## Step 3 — Invoke the `wix-manage` skill
 
-Once `wix.config.json` exists, extract `siteId` (value of the `siteId` field — this is the businessId for all MCP calls in the session).
+**Always invoke `Skill(name="wix-manage")` here** — it is the only thing that publishes `<wix-manage-root>` into scratch **and loads the recipe files into context** (Step 4's installs and the whole Seed phase reuse them; `SEED.md` does not re-invoke). A known directory path is not a substitute — the recipes must be in context. Use the harness's skill-invocation primitive (Claude Code: `Skill(name="wix-manage")`); the prose instruction is the contract — don't hardcode a tool-call snippet.
 
-`cd` into the project directory so all subsequent file operations and shell commands are relative to it.
-
-#### 2. The dispatch itself (one concurrent batch)
-
-**MCP app installs** — one `<prefix>CallWixSiteAPI` per app in the union of loaded packs' `apps[*]`. Example for an ecommerce run (stores pack contributes one app; cms pack contributes none):
+Then read the app-install recipe by absolute path (the `Skill` invocation must precede this Read — it needs the path `wix-manage`'s SKILL.md publishes):
 
 ```
-<prefix>CallWixSiteAPI(
-  siteId: "<siteId>",
-  reason: "Install Wix Stores app for <brand>",
-  sourceDocUrl: "https://dev.wix.com/docs/picasso/wix-ai-docs/recipes-v2/manage/platform/recipe-install-wix-apps",
-  method: "POST",
-  url: "https://www.wixapis.com/apps-installer-service/v1/app-instance/install",
-  body: {
-    tenant: { tenantType: "SITE", id: "<siteId>" },
-    appInstance: { appDefId: "<pack.apps[0].appDefId>", enabled: true }
-  }
-)
+Read <wix-manage-root>/references/app-installation/install-wix-apps.md
 ```
 
-> The `CallWixSiteAPI` schema was already loaded by the Step 0 MCP bootstrap, so `body` is correctly typed as a JSON object on the first call. See `references/shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
-
-A 200 response with `"enabled": true` confirms success.
-
-**Packs with `apps: []` (e.g. `cms`)** — record a phase entry in `run.json` anyway: `{phase: "app-install-<pack>", status: "skipped", notes: "Bundled with Wix platform; no install required"}`. Without an explicit skipped entry, `run.json` reads as a silent omission ("did the CMS install run? was it skipped? did it fail?"); the explicit entry makes observability unambiguous.
-
-**Namespace propagation:** After app install, the app's API namespace may take up to 30 seconds to register. If a downstream MCP call fails with `UNSUPPORTED_FORM_NAMESPACE`, wait 10 seconds and retry up to 3 times. Phase 1 Seeders handle this retry themselves.
-
-**Shell: `npx @wix/cli env pull`** (foreground, ~5s). Writes `WIX_CLIENT_ID` to `.env.local`. Idempotent. Skipping this historically caused `Missing environment variable WIX_CLIENT_ID` build failures.
-
-**Background shell: `npm install ...`**:
-
-The package list is the union of:
-- Always: `@wix/sdk tailwindcss @tailwindcss/vite`
-- Per loaded pack: each pack's `packages` array
-
-> **Do not add any package beyond this set.** If a pack feels like it should have its own SDK (`@wix/<pack-name>`), confirm by reading its `packages:` array. Passive packs (gift-cards) intentionally declare nothing because they're runtime-detected via REST. There is no `@wix/gift-cards` SDK on npm — adding it on a hunch fails with `npm 404`. Same logic for any other pack: the union above is the install list. Period.
+The recipe's Step 2 documents the install body shape:
 
-Flags: `--no-fund --no-audit --legacy-peer-deps`. `--legacy-peer-deps` is mandatory (Wix SDK transitive peer conflicts). `--no-fund --no-audit` prevent interactive prompts that hang agent sessions.
-
-Because scaffold runs with `--skip-install`, delete the stale lockfile before installing: `rm -f package-lock.json`.
-
-Example combined command (ecommerce run):
-```bash
-rm -f package-lock.json && npm install --no-fund --no-audit --legacy-peer-deps \
-  @wix/sdk tailwindcss @tailwindcss/vite \
-  @wix/stores @wix/ecom @wix/redirects @wix/site \
-  @wix/data @wix/essentials
+```
+tenant: { tenantType: "SITE", id: "<siteId>" }
+appInstance: { appDefId: "<pack.apps[N].appDefId>" }
 ```
 
-Capture the background process's handle (whatever your runtime uses to wait on a long-running shell) for later wait in Step 8 (Build & Preview).
-
-**Memory writes** — two writes:
-1. `MEMORY.md` index entry (one line)
-2. `project`-type memory file with brand, vertical(s), apps, pages, project path, phase: `scaffolding`
-
-**User-facing roadmap × N** — target 6–8 entries mapped to phase boundaries:
-
-| Entry | Marks completed |
-|------|-----------------|
-| Scaffold project | Immediately on creation (already done in Discovery) |
-| Install apps | Immediately on creation (this dispatch) |
-| Seed data | After Phase 1 Seed returns (Step 6) |
-| Design site | After Phase 2 Design System returns (Step 4) |
-| Generate images | After image subagent returns (may finish later than critical path) |
-| Wire features | After Phase 3 Components + Phase 4 Pages return (Step 7/8) |
-| Install dependencies | After npm install background shell completes (Step 8) |
-| Build and preview | After Step 8 |
-
-> **No ampersands in roadmap titles.** Some progress trackers HTML-escape input — `"Build & preview"` renders as literal `Build &amp; preview`. Spell out "and" (or restructure) to avoid `&`. Same for `<`, `>`, `"` and other HTML-meaningful characters.
-
-> **Avoid the 13-entry sprawl.** Historical runs used one entry per phase-per-feature ("Design page — Home", "Seed stores", "Wire CMS", etc.). Collapse to the phase-boundary list above. Users care about milestones, not sub-phases.
-
-**Shell: `mkdir -p .wix`** — minimal. No `.wix/logs/`.
-
-### Batching verification
-
-After the dispatch, the run log should show ~8–12 operations dispatched as one concurrent batch (varies by pack count). If they spread across multiple turns, the batching guidance failed and the skill needs to be tightened.
-
----
-
-## npm install recovery
-
-If the background npm install from the Setup dispatch fails or hangs:
-
-1. **Foreground retry with 90-second timeout:**
-   ```bash
-   npm install --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
-
-2. **If still hanging, retry with `--prefer-offline`:**
-   ```bash
-   npm install --prefer-offline --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
+Endpoint: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install`.
 
-3. **If still hanging, clear the cache:**
-   ```bash
-   npm cache clean --force
-   npm install --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
+> **Recipe call shape.** Recipes are authored in `curl` form. Build each call with the headers in `references/shared/AUTHENTICATION.md` (`Authorization: Bearer $TOKEN` + `wix-site-id: $SITE_ID` + `Content-Type: application/json`). The recipe's URL/method/body are the source of truth.
 
-4. **Last resort:** tell the user: *"npm install is hanging. Please run `npm install --legacy-peer-deps` manually in your terminal, then let me know when it's done."*
+> **Missing-skill fallback (only if the `Skill` primitive errors):** fall back to the install body shape above (REST-shaped and stable) and note the missing skill in the run digest. Don't silently substitute — `wix-manage` is the canonical entry point.
 
 ---
 
-## After the Setup Dispatch
-
-Proceed immediately to **Step 3 — Phase 1 Seed + Phase 2 Design System + Image Phase 1** — see `ORCHESTRATION.md`. Do not wait for the background npm install; that's waited on in Step 8.
-
----
+## Step 4 — One concurrent batch
 
-## Existing project flow
+Fire 4a + 4b + 4c as a single concurrent batch (`PLAN.md` § "Batching discipline").
 
-Use this path when the user already has a working frontend on disk (e.g. a Claude Design output, a Vite/React app, a hand-coded `index.html`) and wants to **connect it to Wix Headless** for hosting + Business Solutions. The user explicitly says things like *"connect this to Wix Headless"*, *"add Wix Headless to this project"*, or invokes a prompt that references `wix-headless.dev/skill.md`.
+### 4a. App installs — one `curl` per `pack.apps[*]` (business track, frontend-blind)
 
-**Differences from the new-project flow:**
-
-| Aspect | New project | Existing project |
-|---|---|---|
-| Project creation | `npm create @wix/new@latest headless` (via `scaffold.sh`) — fresh Astro blank template | `npm create @wix/new@latest init` — wraps the existing project, leaves source untouched |
-| Frontend | Generated by Phases 2–5 (Astro + designer + components + pages) | Already exists; orchestrator does **not** generate UI |
-| Seeders / Designer / Pages waves | Run | **Skipped** — there is no Astro structure to populate |
-| App installs | From inferred vertical packs | From a quick **project analysis** (see below) — only apps the existing project actually needs |
-| SDK wiring into source | N/A (designer/pages waves write Astro + SDK calls from scratch) | **Required** — edit the project's existing source files in place to wire each installed app's SDK calls to its corresponding feature surface |
-| Build / release | `npx @wix/cli build` + `release` via `release.sh` | `npx @wix/cli release` directly — **no build step**; the existing `index.html` is published as-is |
-| Entry file | `src/pages/index.astro` (Astro convention) | **Must be `index.html`** at the configured `outputDirectory` |
-
-### Step E1 — Init (replaces scaffold)
-
-`cd` into the existing project directory. Run, foreground (it's interactive-ish but non-blocking with `--yes`-style defaults; capture stdout):
+The install body is identical per `pack.apps[*]` regardless of frontend. Mint the site-scoped REST token once, cache it for the run, then fire one `curl` per `apps:` entry across every loaded pack (top-level + transitive via `requires:`):
 
 ```bash
-npm create @wix/new@latest init
+SITE_ID="<siteId>"
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")  # once; cache in scratch for the run
+
+# per-pack iteration; one curl per pack.apps[*]:
+curl -sS -X POST "https://www.wixapis.com/apps-installer-service/v1/app-instance/install" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant":      { "tenantType": "SITE", "id": "'"$SITE_ID"'" },
+    "appInstance": { "appDefId": "<pack.apps[N].appDefId>", "enabled": true }
+  }'
 ```
 
-> Same package + invoker as Path A's scaffold (`npm create @wix/new@latest headless`), only the subcommand differs: **`init` for existing projects, `headless` for new projects**. Do not combine them (`… headless init` is a known regression).
+Use `npx @wix/cli@latest token …` (not bare `wix token`) — `npx` resolves the project-local CLI the scaffold produced (first call auto-fetches it ~3–5 s if missing). A 200 confirms the install. On 401/403, retry the same call once with the cached token (do **not** re-mint — it's byte-identical for the run; recovery ladder in `references/shared/AUTHENTICATION.md`); a persistent 401 usually means the CLI session expired and `wix login` is required — surface the response body.
 
-This creates a Wix Site + Headless Project (App) connected to that Site, and writes `wix.config.json` in the project root:
+Packs with `apps: []` (`cms`, `ecom`) or `disabled: true` (`gift-cards`, whose `apps:` is empty by design — the user opts in via the dashboard) install nothing — skip the curl.
 
-```jsonc
-{
-  "projectType": "Site",
-  "appId": "16511cb9-3d3a-4371-a04a-bcc176ae5d50", // SDK clientId
-  "siteId": "90b8c952-a7f9-4d79-a2c0-b0ec3e1c1434", // businessId for all MCP calls
-  "site": {
-    "outputDirectory": "./site"  // edit to "./" if the entry file is at project root
-  }
-}
-```
+### 4b. `npx @wix/cli@latest env pull --json`
 
-**Required follow-ups before continuing:**
+Foreground, ~5 s. Writes `WIX_CLIENT_ID` to `.env.local` (idempotent). Skipping it causes `Missing environment variable WIX_CLIENT_ID` build failures downstream. **Always pass `--json`** — without it the CLI emits an interactive spinner that floods the non-TTY pipe with ANSI frames; `--json` gives one clean line (the skill only needs `.env.local` on disk).
 
-1. **Entry file must be `index.html`.** If the project's entry is `index.htm`, `main.html`, etc., either rename to `index.html` or ask the user to confirm renaming. Wix Headless hosting serves `index.html` as the site root; anything else 404s.
-2. **`site.outputDirectory` must point at the directory containing `index.html`.** If `index.html` is at the project root, edit `wix.config.json` and set `"outputDirectory": "./"`. Default is `"./site"` which assumes a build output directory.
-3. Extract `siteId` from `wix.config.json` — same role as in the new-project flow (businessId for every MCP call this session).
-4. Capture timing as `{ phase: "init", seconds: <duration>, started, ended }` in `run.json.phases[]`.
+### 4c. Dispatch background `npm install`
 
-Recovery ladder:
-- Auth error → surface `"Run \`npx @wix/cli login\` and retry."` and stop (same as new-project flow).
-- `init` already ran here (a `wix.config.json` already exists) → skip Step E1, continue to E2.
-- Network / unknown → surface stderr to the user.
+Background shell; capture `npm_handle` + `<npm-tempfile>` in scratch. Trust the exit code at the seed gate — do not probe `node_modules`.
 
-### Step E2 — Analyze the project to decide which apps to install
+```bash
+npm install --no-fund --no-audit --legacy-peer-deps <package-set> \
+  2> <npm-tempfile>
+# dispatched with run_in_background: true; capture as npm_handle
+```
 
-The existing-project flow does NOT use vertical-pack inference from the user prompt. Instead, **read the project files** to decide which Wix Business Solutions are needed. Quick heuristic table:
+`<package-set>` from the resolved pack set (loaded + transitive via `requires:`):
 
-| Signal in source files | Pack(s) to install |
+| Always | Add when pack is loaded |
 |---|---|
-| Mentions of "event", "wedding", "RSVP", "guests", "ceremony" | `events` (if pack exists), else CMS-backed RSVP via `cms` |
-| `<form>` tags, "Contact us", "Get in touch", email collection | `forms` |
-| Product listings, "buy", "$", "add to cart", price tags | `stores` (transitively pulls `ecom`, `gift-cards`) |
-| Article / blog content, post listings | `blog` |
-| Booking, appointments, calendar | `bookings` (if pack exists) |
-| Restaurant menu, dishes | `restaurants` (if pack exists) |
-| Always | `cms` (any user-editable content) |
-
-Read `index.html` and any top-level source files (`*.jsx`, `*.tsx`, `*.html`, `*.js`) to look for these signals. Cap reading at the top 5 source files by size — don't grovel.
-
-> If unsure between two packs, ask the user with `AskUserQuestion`. Don't install everything "just in case" — every app install adds clutter to the user's dashboard.
-
-### Step E3 — Install apps (reuse new-project flow's install mechanism)
-
-For each pack identified in E2, follow `<SKILL_ROOT>/references/commands/install-app.md` — the `CallWixSiteAPI` body, `appName → appDefId` lookup, and recovery ladder are identical to the new-project flow. Capture `{ phase: "app-install-<appName>", seconds }` per install.
-
-Skip the new-project flow's other Wave-2 operations: **no `env pull` is required** for a pure-static site (only needed if the project will call Wix SDK from server-side / build-time code), **no `npm install`** (the existing project manages its own deps), **no `seed-utilities.sh`** (no Astro `src/utils/` to seed), **no `init-site-json.mjs`** (no `.wix/site.json` lifecycle).
-
-> If the user wants to wire Wix SDK calls into the existing project (e.g. submit an RSVP form to a Wix CMS collection), then `env pull` + adding `@wix/sdk` + the relevant `@wix/<pack>` packages to the project's own `package.json` IS needed. Treat that as a follow-up sub-task per-pack and let the user confirm before modifying their `package.json`.
-
-### Step E4 — SDK wiring
+| `@wix/sdk tailwindcss @tailwindcss/vite` | — |
+| | **stores** → `@wix/stores` |
+| | **ecom** (direct or via stores `requires:`) → `@wix/ecom @wix/redirects` |
+| | **blog** → `@wix/blog @wix/ricos @astrojs/rss @astrojs/sitemap` |
+| | **forms** → `@wix/forms` |
+| | **cms** → `@wix/data @wix/essentials` |
+| | **bookings** → `@wix/bookings @wix/essentials` |
+| | **gift-cards** → (none — disabled-by-default pack ships no Astro-time imports) |
 
-Installing apps in E3 only registers them against the Site — the existing frontend still ignores them until SDK calls are wired in. For each app installed in E3, find the matching feature surface in the project's source files (the same surfaces E2 detected) and wire its SDK calls inline.
-
-1. Add `@wix/sdk` + the pack's `packages:` (from `references/verticals/<pack>.md`) to the project's `package.json` (`npm init -y` first if absent), then run the project's install command. `--no-fund --no-audit --legacy-peer-deps`.
-2. Edit the source files in place. Follow call patterns from `<SKILL_ROOT>/references/<pack>/INSTRUCTIONS.md` (translate Astro idioms → the project's framework; SDK calls themselves are framework-agnostic). Initialize the client once per file:
-
-   ```js
-   import { createClient, OAuthStrategy } from "@wix/sdk";
-   const wix = createClient({
-     modules: { /* pack modules */ },
-     auth: OAuthStrategy({ clientId: "<appId from wix.config.json>" }),
-   });
-   ```
-
-   **Always inline the `appId` literal from `wix.config.json`.** No env vars, no `import.meta.env`, no `window.__WIX_CLIENT_ID__` — read `wix.config.json` once and paste the appId string into every `createClient` call. Keeps the static-site case working with no build step.
-
-Capture `{ phase: "sdk-wiring-<pack>", seconds }` per pack.
-
-### Step E5 — Release (no build)
-
-**Do NOT run `release.sh`** in this flow — `release.sh` runs `npx @wix/cli build` first, and there is nothing to build. The existing project's `index.html` and its sibling assets already sit at the configured `site.outputDirectory`; Wix just needs to publish that directory as-is. Calling `build` here either no-ops (wastes ~5–15 s) or fails if the project has no Astro/Vite config the Wix CLI knows how to invoke.
-
-Run release directly:
+Example (resolved set = stores + ecom + gift-cards + cms):
 
 ```bash
-npx @wix/cli release
+npm install --no-fund --no-audit --legacy-peer-deps \
+  @wix/sdk @wix/stores @wix/ecom @wix/redirects \
+  @wix/data @wix/essentials \
+  tailwindcss @tailwindcss/vite \
+  2> <npm-tempfile>
 ```
 
-Capture stdout. The CLI prints `Site published on <url>` on success — extract that URL (same parser logic as `release.sh` uses):
+Use `npm --legacy-peer-deps` — `pnpm` fails against the `@wix/cli` template. **Skipping the per-pack additions makes `astro build` fail with `Rollup failed to resolve import "@wix/<pack>"`** (~30 s recovery). Don't invent packages beyond the table; extend the table for a new vertical.
 
-```bash
-sed -nE 's/.*Site published on ([^[:space:]]+).*/\1/p'
-```
-
-Capture `{ phase: "release", seconds }` around the call. No `{ phase: "build" }` entry in `run.json` for this flow.
-
-Auth-failure recovery: same as `release.sh` — if stderr mentions login, surface `"Run \`npx @wix/cli login\` and retry."` and stop. Transient errors (`ECONNRESET`, `temporarily unavailable`, etc.) — retry up to 3 times with `attempt * 5` second backoff, mirroring `release.sh`.
-
-> **If the project needs a client build** (Vite, React, Webpack, etc.), run the project's own build command manually (e.g. `npm run build`) before `npx @wix/cli release`, and make sure `site.outputDirectory` points at the build output. Do not use `wix build`.
-
-### Step E6 — Final message
+---
 
-Emit **exactly two URLs**, both copy-pasted verbatim from tool output / config (URL discipline from `SKILL.md` § "URL discipline" applies here too):
+## Step 5 — Transition to Seed
 
-1. **Production URL** — bold heading / link at the top. The exact string from `Site published on <url>` in Step E5's stdout. Do not retype or modify.
-2. **Dashboard URL** — `https://manage.wix.com/dashboard/<siteId>` where `<siteId>` is the value from `wix.config.json`.
+Setup prints no summary. Before transitioning to `SEED.md`, confirm: `siteId` + `appId` in scratch (from `wix.config.json`, both non-empty), the cached token mints, every `apps:` pack got a 200 (empty-`apps:` packs skipped), `.env.local` contains `WIX_CLIENT_ID`, and `npm_handle` was dispatched. On any failure, surface it verbatim instead of proceeding.
 
-Skip the new-project flow's perf one-liner phases that didn't run (`design-system`, `images`, etc.). For Path B the perf line is:
+---
 
-> `Connected in <Nm Ss> — init <n>s · app-install <n>s · sdk-wiring <n>s · release <n>s`
+## npm install recovery
 
-`sdk-wiring` aggregates every `sdk-wiring-<pack>` phase from E4.
+Invoked when `npm_handle` returns non-zero (dispatched in Step 4c, waited at the seed gate in `BUILD-astro.md`):
 
-Write a `project`-type memory entry capturing brand (from `wix.config.json`'s implicit project name or ask), siteId, installed apps, and **phase: `connected-existing`** so future sessions know this is an existing-project shell, not a wix-headless-scaffolded build.
+1. **Foreground retry** `npm install --no-fund --no-audit --legacy-peer-deps <packages>` (90 s timeout). If it hangs, add `--prefer-offline`; if still hanging, `npm cache clean --force` and retry once more.
+2. **Last resort:** ask the user to run `npm install --legacy-peer-deps` manually and report back. Don't substitute pnpm/yarn — pnpm fails against the `@wix/cli` template.
 
----
+Package set = the Step 4c table (always-on three ∪ per-pack packages). Don't invent package names.

package/skills/wix-headless/references/{blog → astro/blog}/BLOG_PAGES.md

@@ -114,8 +114,8 @@ const { title, description, pubDate, updatedDate, heroImage, tags = [] } = Astro
   <head>
     <BaseHead title={title} description={description ?? ''} />
     <style is:global>
-      /* All BlogPost layout styles are created by the design skill.
-         See COMPONENT_PATTERNS.md → Blog Post Content for the complete
+      /* All BlogPost layout styles are created by the merged pages scope.
+         See references/shared/STYLING.md (Blog Post Content) for the complete
          styling contract: .hero-image, .prose, .title, .date, .tags,
          .ricos-content overrides, etc. */
     </style>
@@ -182,8 +182,8 @@ const posts = await queryBlogPosts();
   <head>
     <BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
     <style>
-      /* Listing page styles are created by the design skill.
-         Feature skill only wires queryBlogPosts() data. */
+      /* The merged blog-pages scope writes this route once — applying the
+         listing styles and binding queryBlogPosts() data in the same pass. */
     </style>
   </head>
   <body>
@@ -267,6 +267,7 @@ Critical details:
 - **`client:only="react"` is required** — `@wix/ricos` is a React component; `client:only="react"` ensures it renders only on the client, avoiding SSR issues with React-dependent code.
 - **`[...slug]` (rest param)** — uses Astro's rest parameter syntax, not `[slug]`, to match the full slug path.
 - **`RicosViewer`** renders the rich content from the Wix Blog editor (images, videos, text formatting, embeds, etc.) using `quickStartViewerPlugins()` for full content-type support.
+- **Blog deliberately uses the React `RicosViewer`** (full feature set: galleries, polls, embedded media) — not a contradiction with CMS, which uses the lighter SSR `renderRicos` walker (`src/utils/ricos.ts`). Blog posts can carry the full Ricos feature set, so they need the React island; static CMS pages (about/faq/portfolio/team/resource) only need paragraphs + lists and avoid shipping ~80kb of React. See `references/astro/cms/CMS_FOUNDATIONS.md` § "Why not @wix/ricos?".
 - **No `getStaticPaths()`** — Wix headless projects use `output: "server"` (SSR on Cloudflare Workers), so pages use `Astro.params` directly instead of static path generation.
 - **404 handling** — `getPostBySlug` returns `null` for missing posts; redirect to `/blog` listing.
 - **Ricos color overrides** — The BlogPost layout's `<style is:global>` block includes `.ricos-content` overrides that force `var(--color-text)` on all Ricos elements. Without these, blog text is invisible on dark themes.
@@ -296,4 +297,4 @@ export async function GET(context) {
 }
 ```
 
-> Requires the `site` property in `astro.config.mjs` (set in BLOG_SETUP.md step 1).
+> Requires the `site` property in `astro.config.mjs` (set in BLOG_SETUP.md step 1).

package/skills/wix-headless/references/{blog → astro/blog}/BLOG_SETUP.md

@@ -5,7 +5,7 @@ Prerequisites, dependencies, blog service module, and astro config changes for t
 ## Prerequisites
 
 - A Wix Managed Headless project (has `wix.config.json` and `astro.config.mjs`)
-- The **Wix Blog app** installed on the connected Wix site (via MCP after scaffolding, or installed via MCP if missing — see `BLOG_CONTENT.md` Step 0)
+- The **Wix Blog app** installed on the connected Wix site (installed via the apps-installer REST endpoint after scaffolding — see `../../blog/BLOG_CONTENT.md` Step 0)
 - At least one published blog post in the Wix dashboard
 
 ## Package Installation
@@ -215,4 +215,4 @@ Key details:
 - `media.getImageUrl(ref).url` resolves Wix media references to real URLs
 - `getPostBySlug` returns `null` for missing posts — pages must handle this with a redirect
 - `queryBlogPosts()` sorts by `firstPublishedDate` descending (newest first)
-- `RICH_CONTENT` fieldset is required to get renderable content for `RicosViewer`
+- `RICH_CONTENT` fieldset is required to get renderable content for `RicosViewer`