@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -1,58 +1,36 @@
 # Setup
 
-Runs once, immediately after the user approves the plan and Discovery has written `.wix/site.json`. This phase's domain is: install the apps the loaded packs declare, pull the Wix env, run `npm install`, and patch `site.json` with `siteId` + `appId`. Run flow (dispatch timing, background handles, waits, batching, transitions) is owned by `BUILD.md` (Setup is its first run-step).
+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).
 
-This article covers the **astro (supported) entry path** — Steps 1–5 below + "npm install recovery". The orchestrator scaffolds a fresh Astro project via `scaffold.sh` in `BUILD.md` run-step 0; astro is the only frontend built on disk today.
-
-The **Existing project flow (Path B)** at the bottom is **retired** — non-astro (custom) frontends route to the not-available-yet stub (`references/custom/INSTRUCTIONS.md`) instead of running E1–E6. That section is kept as a historical reference only; see its banner.
-
-This path assumes DISCOVERY.md's CLI-auth pre-flight has already passed (the foreground check that runs before any `AskUserQuestion`).
-
-Mode/track routing (which path runs) is owned by `PLAN.md` § "Frontend-mode routing". Steps 1–5 below are the astro business steps.
+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 1 — Read the scaffolded project config (siteId + appId)
 
-**Do not** speculatively `Read <project-slug>/wix.config.json` before the scaffold exists — the speculative read returns `File does not exist` on every fast-Q&A run (the file isn't there yet), emits a `[MED]` anomaly in the trace, and costs 3–5 s of round-trip + recovery thinking.
-
-Once the scaffolded project exists, read `<project-slug>/wix.config.json` and extract:
-- `siteId` — the site id passed as `--site` to `npx @wix/cli@latest token` and embedded in every install body + as the `wix-site-id` header on every site-scoped REST call. Hold it in orchestrator session scratch.
-- `appId` — the project's appId. Hold it in session scratch (it goes into the SDK's `createClient` inputs in later steps).
-
-**Before `cd`, capture the current working directory as `<site-root>` and hold it in session scratch.** This is where Discovery's `init-site-json.mjs` wrote the slim `.wix/site.json` snapshot. The orchestrator is the **sole** reader/writer of that file; no subagent or downstream script reads it during the run. Hold `<site-root>` as an absolute path so the `cd` into the scaffold subdir below does not lose it.
+> **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.
 
-`cd` into `<project-slug>/` so all subsequent file ops + shell calls (`npm`, `npx @wix/cli@latest env pull`) are relative to the project root.
+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.
 
----
-
-## Step 2 — Patch site.json with siteId + appId
-
-Discovery wrote `<site-root>/.wix/site.json` with `brand`, `frontend`, and `verticals`. Setup's only addition is patching `siteId` and `appId` in. This is a one-shot in-process JSON edit:
+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.
 
-1. `Read <site-root>/.wix/site.json` (absolute path — `<site-root>` was captured in Step 1, before the `cd` into the scaffold).
-2. Add the two top-level fields (`siteId`, `appId`) using the values held in session scratch.
-3. `Write` the updated file back to the same absolute path.
-
-The file's purpose at this point is **observability + resume detection** — no subagent reads it; the orchestrator is the sole reader/writer. Six lines of edit doesn't justify a script.
+Capture CWD as `<site-root>` in scratch. No `cd` step — every file op runs in the project root.
 
 ---
 
 ## Step 3 — Invoke the `wix-manage` skill
 
-> **Default — just invoke it; do not deliberate.** **Always** invoke `Skill(name="wix-manage")` here. It is near-instant, and it is the *only* thing that both publishes `<wix-manage-root>` into scratch **and loads the recipe files into context** (which Step 4's installs and the whole Seed phase then reuse — SEED.md reads recipes relative to `<wix-manage-root>` and explicitly does **not** re-invoke). **Knowing the `wix-manage` directory path from an earlier `ls`/discovery is NOT a reason to skip the invocation** — a raw filesystem path is not the same as the skill being loaded (the recipes aren't in context). Do not weigh invoke-vs-skip; invoke. The only exception is the Missing-skill fallback below.
-
-App installation is delegated to `wix-manage`. Use the harness's skill-invocation primitive — in Claude Code that's `Skill(name="wix-manage")`; other harnesses provide an analogous mechanism. **Do not** hardcode a tool-call snippet here; the prose instruction "Invoke the `wix-manage` skill" is the contract, and the harness owns the mechanics. This mirrors `wix-app/SKILL.md:241` ("Invoke the `wix-design-system` skill") and keeps the skill agent-agnostic.
+**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.
 
-After invocation, `wix-manage`'s SKILL.md is in context with absolute paths to its `references/<topic>/` files. Read its app-install recipe by absolute path:
+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):
 
 ```
 Read <wix-manage-root>/references/app-installation/install-wix-apps.md
 ```
 
-> **Sequencing note.** Within Step 3, the `Skill` invocation must precede the `Read install-wix-apps.md` (the Read needs the absolute path that `wix-manage`'s SKILL.md publishes).
-
-The recipe's Step 2 documents the body shape every Step 4 install call will use:
+The recipe's Step 2 documents the install body shape:
 
 ```
 tenant: { tenantType: "SITE", id: "<siteId>" }
@@ -61,23 +39,19 @@ appInstance: { appDefId: "<pack.apps[N].appDefId>" }
 
 Endpoint: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install`.
 
-> **Recipe call shape.** Every loaded `wix-manage` recipe is authored in `curl` form. Build each call with the headers documented in `references/shared/AUTHENTICATION.md` (`Authorization: Bearer $TOKEN` + `wix-site-id: $SITE_ID` + `Content-Type: application/json`). The recipe's URL, method, and body are the source of truth — do not re-derive them.
+> **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.
 
-> **Missing-skill fallback (only when the `Skill` primitive fails).** This applies **only** when the skill-invocation primitive itself is unavailable — i.e. `wix-manage` is not installed in the current harness and the `Skill(name="wix-manage")` call errors. It is **not** a "use the path you already found" shortcut: a known directory path never justifies skipping the invocation (see the default above). When the invocation genuinely fails, fall back to the install **body shape** documented above (it is REST-shaped and stable; the recipe wraps it but does not transform it), and note the missing skill in the run digest. Do not silently substitute — the canonical entry point is `wix-manage`.
+> **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.
 
 ---
 
 ## Step 4 — One concurrent batch
 
-> Fire 4a + 4b + 4c as a single concurrent batch — see `PLAN.md` § "Batching discipline".
-
-The dispatch contains three operations:
+Fire 4a + 4b + 4c as a single concurrent batch (`PLAN.md` § "Batching discipline").
 
 ### 4a. App installs — one `curl` per `pack.apps[*]` (business track, frontend-blind)
 
-This is **business-track** work: the install body is identical per `pack.apps[*]` regardless of the `frontend`/template — it registers Wix apps against the Site and never reads which frontend will consume them.
-
-Mint the site-scoped REST token once and cache it for the rest of the run, then iterate every loaded pack (top-level + transitive via `requires:`) and fire one `curl` per entry in the pack's `apps:` array:
+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
 SITE_ID="<siteId>"
@@ -94,23 +68,17 @@ curl -sS -X POST "https://www.wixapis.com/apps-installer-service/v1/app-instance
   }'
 ```
 
-Use `npx @wix/cli@latest token …` (not bare `wix token …`): `@wix/cli` may not be globally installed in every harness, and `npx` resolves to the project-local copy that scaffold just produced. The first invocation auto-fetches the CLI (~3–5 s) if missing; subsequent calls are instant.
-
-A 200 response confirms the install. On 401/403, retry the same call once with the cached token per the recovery ladder in `references/shared/AUTHENTICATION.md` — do **not** re-mint (the token is byte-identical for the run); if it still fails, surface the response body — a persistent 401 usually means the CLI session expired and `wix login` is required.
-
-**Packs with `apps: []` (e.g. `cms`, `ecom`):** skip the curl but record a phase entry as `{phase: "app-install-<pack>", status: "skipped", notes: "no app required for this pack"}` — the explicit skipped entry keeps run observability unambiguous.
+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.
 
-**Packs with `disabled: true` (today: `gift-cards`):** the pack still loads and contributes to the resolved set, but its `apps:` array is empty by design (the user opts in via the dashboard later). No curl. Same `skipped` phase entry as above.
+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.
 
 ### 4b. `npx @wix/cli@latest env pull --json`
 
-Foreground shell, ~5 s. Writes `WIX_CLIENT_ID` to `.env.local`. Idempotent. Skipping this causes `Missing environment variable WIX_CLIENT_ID` build failures in downstream phases.
-
-> **Always pass `--json`.** Without it the CLI renders an interactive spinner; captured through the tool's non-TTY pipe, every animation frame lands as a separate line of ANSI escapes (`\x1b[2K\x1b[1A…⠙ Pulling…`) and bloats the context for zero signal. `--json` selects the CLI's non-interactive render-to-string path (one clean `{"success": true}` line), and the skill doesn't parse this command's output anyway — it only needs `.env.local` on disk.
+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).
 
 ### 4c. Dispatch background `npm install`
 
-Run `npm install` as a backgrounded shell. Capture the handle as `npm_handle` and the path to `<npm-tempfile>`. Hold both in session scratch.
+Background shell; capture `npm_handle` + `<npm-tempfile>` in scratch. Trust the exit code at the seed gate — do not probe `node_modules`.
 
 ```bash
 npm install --no-fund --no-audit --legacy-peer-deps <package-set> \
@@ -118,193 +86,44 @@ npm install --no-fund --no-audit --legacy-peer-deps <package-set> \
 # dispatched with run_in_background: true; capture as npm_handle
 ```
 
-`<package-set>` is composed from the resolved pack set (loaded packs from Setup Step 1, including transitives via `requires:`):
+`<package-set>` from the resolved pack set (loaded + transitive via `requires:`):
 
 | Always | Add when pack is loaded |
 |---|---|
 | `@wix/sdk tailwindcss @tailwindcss/vite` | — |
 | | **stores** → `@wix/stores` |
-| | **ecom** (loaded directly or as `requires:` of stores) → `@wix/ecom @wix/redirects` |
+| | **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/wix-data-items-sdk @wix/essentials` |
+| | **cms** → `@wix/data @wix/essentials` |
+| | **bookings** → `@wix/bookings @wix/essentials @wix/forms @wix/redirects @wix/auto_sdk_ecom_cart-v-2` |
 | | **gift-cards** → (none — disabled-by-default pack ships no Astro-time imports) |
 
-Concrete example for the most common case (stores prompt; resolved set = stores + ecom + gift-cards + cms):
+Example (resolved set = stores + ecom + gift-cards + cms):
+
 ```bash
 npm install --no-fund --no-audit --legacy-peer-deps \
   @wix/sdk @wix/stores @wix/ecom @wix/redirects \
-  @wix/data @wix/wix-data-items-sdk @wix/essentials \
+  @wix/data @wix/essentials \
   tailwindcss @tailwindcss/vite \
   2> <npm-tempfile>
 ```
 
-> **Why three packages for cms?** `@wix/data` exposes collections / permissions / backups namespaces; the actual `items` API (used by every CMS page for queries) lives in `@wix/wix-data-items-sdk` since `@wix/data` 1.0.448 dropped the `items` re-export (see [astro/cms/CMS_FOUNDATIONS.md](./astro/cms/CMS_FOUNDATIONS.md) § "Import note"). `@wix/essentials` is required for `auth.elevate` — every CMS page elevates queries to bypass per-collection permission checks. Shipping only `@wix/data` produces `'items' is not exported by '@wix/data'` at `astro build`; shipping without `@wix/essentials` produces `Cannot find module '@wix/essentials'` at SSR time.
-
-Per pre-flight S0.2, `pnpm install` fails against the `@wix/cli` template — use `npm install --legacy-peer-deps`.
-
-**Why per-pack packages live here, not in pack frontmatter:** `references/verticals/_schema.md` is scoped to Discovery; it deliberately excludes `packages:` to keep that schema small. The install set is owned by SETUP.md instead — the lookup table above is the contract. **If you skip the per-pack additions and ship only the always-on three, `astro build` fails at Wave 5 with `Rollup failed to resolve import "@wix/stores"` (or whichever pack-side package the run depends on) and Setup's win on the foreground wall is paid back many times over in a recovery cycle.** When this happens, the build retries after an in-flight `npm install @wix/stores @wix/ecom`, costing ~30 s.
-
-Do not invent packages beyond the table above. If a future vertical needs a new package, extend the table here.
+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.
 
 ---
 
 ## Step 5 — Transition to Seed
 
-Setup does not print a summary sentence. Setup ends once the Final-scan checks pass.
+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.
 
 ---
 
 ## npm install recovery
 
-Invoked when `npm_handle` returns non-zero. The handle is dispatched in Step 4c above; the orchestrator waits on it at the seed gate (`BUILD.md`) and runs this recovery ladder there if it failed.
-
-If the background `npm install` fails or hangs:
-
-1. **Foreground retry** with `npm install --no-fund --no-audit --legacy-peer-deps <packages>` (90 s timeout). If that hangs, add `--prefer-offline`; if still hanging, run `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. Do not silently substitute pnpm/yarn — pre-flight S0.2 confirmed pnpm fails against the `@wix/cli` template.
-
-The package set is the union of `@wix/sdk tailwindcss @tailwindcss/vite` (always) plus each loaded pack's frontmatter `packages:` array. The current pack frontmatter does not declare `packages:` blocks — vertical packs are discovery-only at this phase, so the install set is just the always-on three. Do not invent package names.
-
----
-
-## Final scan (MANDATORY)
-
-Before transitioning to SEED.md in Step 5, verify: `siteId` + `appId` are in `.wix/site.json` (extracted from `wix.config.json`, both non-empty), the cached token mints, every loaded pack with `apps:` got a 200 OK (or a `skipped` phase entry for empty `apps:`), `.env.local` contains `WIX_CLIENT_ID`, and `npm_handle` was dispatched. If any check fails, surface the failure verbatim instead of transitioning to SEED.md.
-
----
-
-## Existing project flow (Path B) — RETIRED, historical reference only
-
-> **⚠️ This flow is no longer dispatched.** Non-astro (custom) frontends now route to the **not-available-yet stub** (`references/custom/INSTRUCTIONS.md`); the conductor does not run E1–E6 (`PLAN.md` § "Custom (non-astro) frontends — not available yet", `DISCOVERY.md` § "Custom (non-astro) — not available yet"). The E1–E6 mechanics below — especially the **E4 SDK-wiring recipe** — are retained as the **historical reference / closest prior art** for the eventual custom authoring track (`references/custom/INSTRUCTIONS.md` § "Intended future shape" step 3). Do **not** dispatch this flow; it is documentation, not a live path.
-
-This path used to run when the user already had a working frontend on disk (Claude Design output, Vite/React app, hand-coded `index.html`) and wanted to **connect it to Wix Headless** for hosting + Business Solutions.
-
-**Differences from Path A:**
-
-| Aspect | Path A (new project) | Path B (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 Designer + Components + Pages subagents | Already exists; orchestrator does **not** generate UI |
-| Seeders / Designer / Pages / BUILD | Run | **Skipped** — there is no Astro structure to populate |
-| App installs | From inferred vertical packs | From a quick **project analysis** (see E2) — only apps the existing project actually needs |
-| SDK wiring into source | N/A (subagents write Astro + SDK calls from scratch) | **Required (E4)** — edit the project's existing source files in place |
-| Build / release | `npx @wix/cli@latest build` + `release` via `release.sh` | `npx @wix/cli@latest release` directly — **no build step**; 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):
-
-```bash
-npm create @wix/new@latest init
-```
-
-> 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).
-
-This creates a Wix Site + Headless Project (App) connected to that Site, and writes `wix.config.json` in the project root:
-
-```jsonc
-{
-  "projectType": "Site",
-  "appId": "16511cb9-3d3a-4371-a04a-bcc176ae5d50",   // SDK clientId
-  "siteId": "90b8c952-a7f9-4d79-a2c0-b0ec3e1c1434",  // siteId for every REST call this session
-  "site": {
-    "outputDirectory": "./site"  // edit to "./" if the entry file is at project root
-  }
-}
-```
-
-**Required follow-ups before continuing:**
-
-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, use the `Edit` tool on `wix.config.json` to set `"outputDirectory": "./"`. Default is `"./site"` which assumes a build output directory.
-3. Extract `siteId` and `appId` from `wix.config.json` and hold in session scratch (same role as Path A: `siteId` is the `wix-site-id` header on every REST call).
-4. Capture `{ phase: "init", seconds, started, ended }` in `run.json.phases[]`.
-
-Recovery ladder:
-- Auth error → surface `"Run \`npx @wix/cli@latest login\` and retry."` and stop (same as Path A; full ladder in `references/shared/AUTHENTICATION.md`).
-- `wix.config.json` already exists → skip E1, continue to E2.
-- Network / unknown → surface stderr to the user.
-
-### Step E2 — Analyze the project to decide which apps to install
-
-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:
-
-| Signal in source files | Pack(s) to install |
-|---|---|
-| 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
-
-For each pack identified in E2, fire the install `curl` per § Step 4a above — same `tenant` / `appInstance` body, same headers, same recovery ladder (delegated to `wix-manage` per Step 3). Capture `{ phase: "app-install-<pack>", seconds }` per install.
-
-**Skip the rest of Path A's Step 4 batch:** no `env pull` for a pure-static site (only needed if E4 below adds SDK code that reads `WIX_CLIENT_ID` at build time; if so, run `env pull` then), **no `npm install`** (the existing project manages its own deps), **no `seed-utilities.sh`** (it is frontend-track project prep for a skill-scaffolded project; integrate mode has no such project and skips Seed entirely, so the orchestrator never calls it in this flow). `.wix/site.json` itself **was** written by Discovery's "After Approval" step with `frontend: "user-provided"` — that snapshot stays for observability; do not write it again here.
-
-### Step E4 — SDK wiring
-
-> **The custom frontend track is the long-term home for this step.** When the custom track is built, this SDK-wiring recipe becomes per-pack wiring guides under `references/custom/<pack>/…` that inject `@wix/sdk` calls into the user's existing files (additive-only) — see `references/custom/INSTRUCTIONS.md` § "Intended future shape" step 3. Until that lands, this inline recipe is the **historical reference** (the flow itself is retired — non-astro frontends route to the stub, see the banner at the top of this section).
-
-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 § Step 4c's lookup table above) to the project's `package.json` (`npm init -y` first if absent), then run the project's install command with `--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@latest 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:
-
-```bash
-npx @wix/cli@latest release
-```
-
-Capture stdout. The CLI prints `Site published on <url>` on success — extract that URL (same parser logic as `release.sh` uses):
-
-```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@latest 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@latest 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):
-
-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`.
-
-Skip Path A's perf one-liner buckets that didn't run. 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`
+Invoked when `npm_handle` returns non-zero (dispatched in Step 4c, waited at the seed gate in `BUILD-astro.md`):
 
-`sdk-wiring` aggregates every `sdk-wiring-<pack>` phase from E4.
+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.
 
-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.
+Package set = the Step 4c table (always-on three ∪ per-pack packages). Don't invent package names.

package/skills/wix-headless/references/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.

package/skills/wix-headless/references/astro/bookings/COMPONENTS.md

@@ -0,0 +1,45 @@
+# Bookings Components — the client islands (astro)
+
+The `components` scope of the bookings vertical. You write the React islands that
+power the booking UI. The **logic** is in `../../bookings/FLOW.md` (read it first);
+this doc is the astro wiring + the gotchas. `src/styles/components-bookings.css`
+and `src/components/bookingDriver.ts` are pre-copied — do **not** write them.
+
+Read `references/shared/IMPLEMENTER.md` + `references/shared/STYLING.md` first.
+
+> **Start from the templates — don't re-author the SDK wiring.** Each island has
+> an example at `<SKILL_ROOT>/references/astro/templates/bookings/`. Read and adapt
+> (brand copy, styling, class names already in `components-bookings.css`); keep the
+> SDK calls + payload shapes.
+
+## Islands you write
+
+| File | From template | Role |
+|------|---------------|------|
+| `src/components/ServiceBookingFlow.tsx` | `…/ServiceBookingFlow.tsx` | `client:only` coordinator — holds the selected slot, swaps calendar → form, redirects on success. Mounted by `services/[slug].astro`. |
+| `src/components/AvailabilityCalendar.tsx` | `…/AvailabilityCalendar.tsx` | the **week calendar** — week strip + nav → the picked day's slots. APPOINTMENT → `availabilityTimeSlots`; CLASS → `eventTimeSlots`. |
+| `src/components/BookingForm.tsx` | `…/BookingForm.tsx` | the **schema-driven** form — renders the `@wix/forms` field list (passed in from the SSR page), keys values by `target`, calls `bookingDriver.book()`. |
+
+## astro-specific rules
+
+1. **Islands call `@wix` ambiently — no `createClient`/`OAuthStrategy`.** In an
+   astro browser island the `@wix/astro` visitor client is ambient (the same way
+   the ecom `CartView` island works): `import { availabilityTimeSlots } from "@wix/bookings"`
+   and call it directly. Do **not** build an `OAuthStrategy` client or read
+   `WIX_CLIENT_ID` — that pattern is for own/static builds (`../../custom/bookings/WIRING.md`).
+2. **The booking sequence is imported, not re-authored.** Import `book`,
+   `navigateToCheckout`, `BookResultType`, and the `SelectedSlot` type from the
+   pre-copied `./bookingDriver`. The form island calls `book(...)` and branches:
+   `CheckoutRequired` → `navigateToCheckout(cartId, postFlowUrl)`; `CheckoutSkipped`
+   → redirect to `/booking-confirmation`.
+3. **Mount everything `client:only="react"`.** Availability + booking are
+   timezone/session-specific; never SSR them.
+4. **The form fields come from SSR.** `services/[slug].astro` fetches the booking
+   form schema and passes a `fields` array into `ServiceBookingFlow` → `BookingForm`
+   (see `SERVICES_PAGES.md`). The island renders the fields generically — it does
+   not fetch the schema itself.
+5. **No CSS.** The classes (`.availability-*`, `.time-slot*`, `.booking-*`) are in
+   the pre-copied `components-bookings.css`; reference them, don't write them.
+
+## Return
+`{ status, phase, scope: "components", summary, data, files, errors }`. If a pre-copied dependency (`bookingDriver.ts`, `components-bookings.css`) is missing, return `status: "partial"` with the coded error.

package/skills/wix-headless/references/astro/bookings/SERVICES_PAGES.md

@@ -0,0 +1,58 @@
+# Bookings Pages — the SSR routes (astro)
+
+The `pages` scope of the bookings vertical. You write the route files. The
+**logic** is in `../../bookings/FLOW.md` (read it first); this doc is the astro
+wiring + the gotchas. Read `references/shared/IMPLEMENTER.md` +
+`references/shared/STYLING.md` first.
+
+> **Start from the templates — don't re-author the SSR data access.** Examples at
+> `<SKILL_ROOT>/references/astro/templates/bookings/`: `ServiceCard.astro`,
+> `services/index.astro`, `services/[slug].astro`, `booking-confirmation.astro`.
+> Read and adapt (copy, headings, styling); keep the SDK query shapes.
+
+## Pages you write
+
+| File | From template | Role |
+|------|---------------|------|
+| `src/pages/services/index.astro` | `…/services/index.astro` | SSR catalog grid (SEO). `queryServices` via ambient `@wix/essentials`. |
+| `src/components/ServiceCard.astro` | `…/ServiceCard.astro` | static service card for the grid. |
+| `src/pages/services/[slug].astro` | `…/services/[slug].astro` | SSR detail (SEO) + mounts `<ServiceBookingFlow client:only="react">`. Also fetches the **booking-form schema** and passes `fields` to the island. |
+| `src/pages/booking-confirmation.astro` | `…/booking-confirmation.astro` | confirmation — renders from the `service`/`startDate` query params (no re-fetch). |
+
+Plus the nav/home links (shell chain — see below).
+
+## astro-specific rules
+
+1. **SSR reads use the ambient `@wix/essentials` client — never `OAuthStrategy`.**
+   `const result = await auth.elevate(services.queryServices)({ query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } }, conditionalFields: ["STAFF_MEMBER_DETAILS"] }).find();`
+   Building `createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) })`
+   in frontmatter 500s in the deployed runtime (the env var is client-only).
+   Always include **`appId`** in the filter. Single service by slug: the
+   `.eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find()` chain.
+2. **The detail page fetches the booking-form schema server-side.** Read
+   `service.form._id`'s form via `@wix/forms` (`auth.elevate(forms.getForm)(formId)`),
+   map `formFields` to `{ label, target, required, componentType, identifier, options }`,
+   and pass the array as `fields` into `<ServiceBookingFlow>`. **Filter to fields with a
+   recognized string `componentType`** (`TEXT_INPUT`/`PHONE_INPUT`/`DROPDOWN`) — skip
+   complex object-valued fields (e.g. the default form's multi-line `ADDRESS`), or
+   `createBooking` fails with "must be object". Pass the full `service` too — the
+   booking step reads its payment/policy. Same field-mapping as `../forms/CONTACT_FORM.md`.
+3. **Only the read pages are SSR.** The detail page SSRs the service info for SEO,
+   then the booking UI runs in the `client:only` island. Do not SSR availability.
+4. **Confirmation renders from query params.** The booking step redirects with
+   `?service=…&startDate=…`; render those. Do not re-fetch a stranger's booking
+   from this public page.
+5. **Two dirs deep** (`services/[slug].astro`) → import with `../../`, not `../../../`.
+
+## Shell chain — nav + home (this scope patches shared files)
+
+- **Navigation** — at `<!-- nav:links -->` in `src/components/Navigation.astro`,
+  append a link to **`/services`** (label fitting the brand: "Book", "Services", "Appointments").
+- **Home** — at `<!-- home:bookings -->` in `src/pages/index.astro`, add a short,
+  brand-voiced CTA linking to **`/services`** (heading + a line + a button-styled
+  link). Use the site's primary-action token (`--color-accent`). Do not list
+  specific services or hardcode slugs — the catalog renders them live.
+- Append at the markers; keep the markers; never replace other packs' insertions.
+
+## Return
+`{ status, phase, scope: "pages", summary, data, files, errors }`. Run the pre-return file-existence assertion (`../../bookings/INSTRUCTIONS.md`). If `index.astro`/`Navigation.astro` lacks its marker, return `status: "partial"` with the coded error.

package/skills/wix-headless/references/astro/cms/CMS_FOUNDATIONS.md

@@ -4,7 +4,7 @@ The **rendering / code-patterns** half of CMS foundations: service module templa
 
 > **Seeding lives in the business track.** Creating collections and inserting/verifying items via REST is **not** here — it is in `<SKILL_ROOT>/references/cms/CMS_FOUNDATIONS.md` (the `seed` scope's doc). This file is consumed by the `pages` scope; that file by the `seed` scope. The `cms/INSTRUCTIONS.md` router points each scope at the right half.
 
-> **Import note (read first).** Page code in this plugin uses `import * as items from "@wix/wix-data-items-sdk"` rather than the documented `import { items } from "@wix/data"`. The Wix-headless docs still show the `@wix/data` form, but `@wix/data` 1.0.448 dropped the `items` re-export — only sub-namespaces (`backups`, `collections`, `permissions`, …) remain, and the documented form fails the build with `'items' is not exported by '@wix/data'`. The actual `items` API (with `query`, `insert`, `update`, `remove`, `bulkInsert`, etc.) lives in `@wix/wix-data-items-sdk`, which `@wix/data` depends on transitively. Importing from there directly works on every current `@wix/data` version. SETUP.md's per-pack install table (Step 4c) installs `@wix/wix-data-items-sdk` (alongside `@wix/data` and `@wix/essentials`) for the cms pack so it's always present. Use the wix-data-items-sdk import everywhere.
+> **Import note (read first).** The Wix Data items API is the **`items`** named export of **`@wix/data`**: `import { items } from "@wix/data"`, then `items.query` / `items.insert` / `items.update` / `items.remove` (plus `items.bulkInsert` / `bulkSave` / `bulkPatch` / …). This is the documented form and what every CMS page here uses. Do **not** import from the internal `@wix/wix-data-items-sdk`. SETUP.md's per-pack install table (Step 4c) installs `@wix/data` + `@wix/essentials` for the cms pack.
 
 ## Rendering Ricos rich-text fields
 
@@ -14,7 +14,7 @@ For SSR Astro pages (about, faq, portfolio, team, resource), import the seeded `
 
 ```astro
 ---
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { renderRicos } from "../utils/ricos";
 
@@ -46,7 +46,7 @@ The util covers the common subset (PARAGRAPH, HEADING 1-6, BULLETED_LIST / ORDER
 
 ## Prerequisites (page-side)
 
-- `@wix/data` + `@wix/wix-data-items-sdk` + `@wix/essentials` installed (collected by SETUP.md Step 4c — do NOT install independently).
+- `@wix/data` + `@wix/essentials` installed (collected by SETUP.md Step 4c — do NOT install independently).
 - The collections + items already created and seeded by the `seed` scope (see `../../cms/CMS_FOUNDATIONS.md`). Pages only **read**.
 
 ## Collection ID Format
@@ -65,7 +65,7 @@ For pages that just need to list items from a collection:
 
 ```astro
 ---
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 
 // Always elevate queries for permission safety
@@ -93,7 +93,7 @@ const myItems = results.map((item) => ({
 Every CMS use case follows the same `src/lib/{usecase}.ts` pattern — a typed interface and query functions that pages import.
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 

package/skills/wix-headless/references/astro/cms/FAQ_KNOWLEDGE_BASE.md

@@ -6,7 +6,7 @@ Build a FAQ page using `@wix/data` — Q&A pairs organized by category with acco
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -32,7 +32,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. FAQ Service Module (`src/lib/faq.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 
 const COLLECTION_ID = "FAQ";
@@ -169,7 +169,7 @@ export default function FaqSection({ categories }: Props) {
 }
 ```
 
-> **Styling note:** Uses `.faq-search`, `.faq-section`, `.faq-category`, `.faq-item`, `.faq-question`, `.faq-toggle`, `.faq-answer` from the designed component's `<style is:global>` block. See `COMPONENT_PATTERNS.md` → FAQ Accordion.
+> **Styling note:** Uses `.faq-search`, `.faq-section`, `.faq-category`, `.faq-item`, `.faq-question`, `.faq-toggle`, `.faq-answer` from the designed component's `<style is:global>` block. See `references/shared/STYLING.md` (FAQ Accordion).
 
 Key details:
 - `<details>/<summary>` for native accordion behavior — no JavaScript needed for open/close
@@ -222,10 +222,10 @@ Key details:
 
 ## Testing
 
-1. Create a "FAQ" collection in the Wix dashboard → CMS with the schema above
-2. Add 6+ FAQ items across 2+ categories, all with `published: true`
-3. Run `npx @wix/cli@latest dev`
-4. `/faq` — shows all questions grouped by category
-5. Click a question — accordion opens with the answer
-6. Type in search — filters questions in real-time
-7. Click a category jump link — scrolls to that section
+Assumes the `seed` scope has already created the "FAQ" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — with 6+ FAQ items across 2+ categories, all `published: true`.
+
+1. Run `npx @wix/cli@latest dev`
+2. `/faq` — shows all questions grouped by category
+3. Click a question — accordion opens with the answer
+4. Type in search — filters questions in real-time
+5. Click a category jump link — scrolls to that section