@wix/agent-skills 1.5.0 → 1.7.0

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

@@ -1,154 +1,310 @@
 # 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, 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).
 
-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 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.
 
 ---
 
-## 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.
+**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.
 
-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.
-   ```
+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).
 
-See `references/shared/MCP_PREFIX.md` for the tool-not-found recovery procedure that subagents use if the prefix somehow fails downstream.
+**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.
 
-> **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.
+`cd` into `<project-slug>/` so all subsequent file ops + shell calls (`npm`, `npx @wix/cli@latest env pull`) are relative to the project root.
 
 ---
 
-## Setup Dispatch — one concurrent batch
+## Step 2 — Patch site.json with siteId + appId
 
-> **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.
+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:
 
-### Contents of the setup dispatch
+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 skill assembles this dispatch dynamically from the loaded vertical packs. The items below list what to emit.
+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.
 
-#### 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).
+> **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.
 
-`cd` into the project directory so all subsequent file operations and shell commands are relative to it.
+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.
 
-#### 2. The dispatch itself (one concurrent batch)
+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:
 
-**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):
+```
+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:
 
 ```
-<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 }
-  }
-)
+tenant: { tenantType: "SITE", id: "<siteId>" }
+appInstance: { appDefId: "<pack.apps[N].appDefId>" }
 ```
 
-> 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".
+Endpoint: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install`.
 
-A 200 response with `"enabled": true` confirms success.
+> **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.
 
-**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.
+> **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`.
 
-**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.
+## Step 4 — One concurrent batch
 
-**Background shell: `npm install ...`**:
+> Fire 4a + 4b + 4c as a single concurrent batch — see `PLAN.md` § "Batching discipline".
 
-The package list is the union of:
-- Always: `@wix/sdk tailwindcss @tailwindcss/vite`
-- Per loaded pack: each pack's `packages` array
+The dispatch contains three operations:
 
-> **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.
+### 4a. App installs — one `curl` per `pack.apps[*]` (business track, frontend-blind)
 
-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.
+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.
 
-Because scaffold runs with `--skip-install`, delete the stale lockfile before installing: `rm -f package-lock.json`.
+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:
 
-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
+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 }
+  }'
 ```
 
-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).
+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.
 
-**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`
+**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.
 
-**User-facing roadmap × N** — target 6–8 entries mapped to phase boundaries:
+### 4b. `npx @wix/cli@latest env pull --json`
 
-| 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 |
+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.
 
-> **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.
+> **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.
 
-> **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.
+### 4c. Dispatch background `npm install`
 
-**Shell: `mkdir -p .wix`** — minimal. No `.wix/logs/`.
+Run `npm install` as a backgrounded shell. Capture the handle as `npm_handle` and the path to `<npm-tempfile>`. Hold both in session scratch.
+
+```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
+```
+
+`<package-set>` is composed from the resolved pack set (loaded packs from Setup Step 1, including transitives 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` |
+| | **blog** → `@wix/blog @wix/ricos @astrojs/rss @astrojs/sitemap` |
+| | **forms** → `@wix/forms` |
+| | **cms** → `@wix/data @wix/wix-data-items-sdk @wix/essentials` |
+| | **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):
+```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 \
+  tailwindcss @tailwindcss/vite \
+  2> <npm-tempfile>
+```
 
-### Batching verification
+> **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.
 
-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.
+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.
+
+---
+
+## Step 5 — Transition to Seed
+
+Setup does not print a summary sentence. Setup ends once the Final-scan checks pass.
 
 ---
 
 ## npm install recovery
 
-If the background npm install from the Setup dispatch fails or hangs:
+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.
 
-1. **Foreground retry with 90-second timeout:**
-   ```bash
-   npm install --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
+If the background `npm install` fails or hangs:
 
-2. **If still hanging, retry with `--prefer-offline`:**
-   ```bash
-   npm install --prefer-offline --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
+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.
 
-3. **If still hanging, clear the cache:**
-   ```bash
-   npm cache clean --force
-   npm install --no-fund --no-audit --legacy-peer-deps <packages>
-   ```
+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.
+
+---
 
-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."*
+## 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.
 
 ---
 
-## After the Setup Dispatch
+## 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`
+
+`sdk-wiring` aggregates every `sdk-wiring-<pack>` phase from E4.
 
-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.
+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/skills/wix-headless/references/astro/COMPOSE.md

@@ -0,0 +1,142 @@
+---
+name: design-system-composer
+description: "The Composer role of the wix-headless design-system phase. Applies the Designer's framework-agnostic design spec to the astro frontend by SUBSTITUTING into pinned skeletons at references/astro/templates/ — it does not re-author the fixed bulk. Maps semantic token values to the @theme vocabulary, writes the 6 design-system files (global.css, astro.config.mjs, Layout.astro, Navigation.astro, Footer.astro, index.astro), and owns the component-CSS token contract (every var(--token) a components-<pack>.css references must resolve). Returns a manifest."
+---
+
+# Composer — how the design becomes code
+
+You are the **Composer**. The Designer already decided *what the brand looks like* and returned it as a framework-agnostic spec. Your job is *how that becomes code* for the **astro** frontend: you map the spec onto the framework's token vocabulary and **substitute it into pinned skeletons**. You do **not** re-author the fixed bulk — the View-Transitions script, the view-transition / `.nav-progress` CSS, the `@utility btn` family, the `process.env` fix, the markers — all of that is literal in the skeletons. Read a skeleton, fill its `{{…}}` slots, write the file. Substitute; do not re-write.
+
+This is deterministic work against pinned templates, so it is fast and low-variance. The whole reason the rewrite-from-scratch failure mode (which roughly doubled the old design-system wall) is gone is that you never regenerate the bulk.
+
+> **Framework:** astro only. The skeletons live at `<SKILL_ROOT>/references/astro/templates/`. Custom (non-astro) frontends never reach the Composer — they route to the not-available-yet stub (`references/custom/INSTRUCTIONS.md`) before the build flow runs. If your prompt ever names a non-astro frontend, return `status: "failed"` with `errors: [{code: "FRONTEND_NOT_SUPPORTED"}]` — do not improvise a second framework.
+
+## Self-Loading
+
+1. Read `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` — structured-return format.
+2. Read `<SKILL_ROOT>/references/shared/STYLING.md` — the three styling categories and, in particular, § "Required tokens — the component-CSS template contract" (the token set you must guarantee). You own that contract now.
+
+No REST calls, no MCP — this is frontend-only work.
+
+**Do NOT `Read .wix/site.json`.** Every input is inlined in your prompt.
+
+## Inputs (entirely from your prompt)
+
+- **`designTokens`** — the Designer's spec (`colors`, `fonts`, `spacing`, `radii`, `containers`), bare-key form.
+- **`shell`** — brand-voice strings: `heroHeadline`, `heroSub`, `footerTagline`, `navBrandMark`.
+- **Brand** — `{ name, description }`.
+- **Navigation links** — JSON array of `{href, label}`. Use labels **verbatim**.
+- **Loaded packs**, **Packs with components**, **Disabled packs** — comma-joined lists.
+- **Project directory** — the scaffold subdir (CWD).
+
+## What you write (the 6 files)
+
+Read each skeleton from `<SKILL_ROOT>/references/astro/templates/`, substitute, write to the project. The fixed bulk in every skeleton is literal — change only the documented `{{…}}` slots.
+
+> **Read skeletons by file, never the directory (`EISDIR`).** `Read <SKILL_ROOT>/references/astro/templates/` fails with `EISDIR: illegal operation on a directory` and costs a wasted recovery round-trip. Read each of the six by its exact path: `<SKILL_ROOT>/references/astro/templates/global.css`, `…/astro.config.mjs`, `…/Layout.astro`, `…/Navigation.astro`, `…/Footer.astro`, `…/index.astro` (issue the six `Read`s as one concurrent batch). If you must discover them first, `Glob` the directory (`…/templates/*`) — never `Read` it.
+
+**Pre-write: scaffold may still be in flight.** A scaffold file you need (`Layout.astro` stub, `astro.config.mjs`) may not yet be present. Before reading one, if a `Read` returns "file does not exist", wait 5 s and retry, cap 6 attempts (~30 s). The 6-attempt cap is hard — do not check a 7th time; return `status: "failed"` with `errors: [{code: "SCAFFOLD_NOT_COMPLETE"}]` immediately on attempt 6's miss. (Reading the *skeletons* under `<SKILL_ROOT>` never needs this — they are always present.)
+
+**Read each destination before you overwrite it.** The scaffold ships stubs for several of your six targets (today: `src/layouts/Layout.astro`, `src/pages/index.astro`, `astro.config.mjs`). The harness **blocks a `Write` to an existing file you have not `Read` this run** (`File has not been read yet`). So your batched reads must include the *destination* project paths for any file the scaffold created — not only the `<SKILL_ROOT>` skeletons. Practically: in the same concurrent batch, `Read` both the skeleton and the destination for `Layout.astro`, `index.astro`, and `astro.config.mjs` (the latter you read anyway to merge); `global.css`, `Navigation.astro`, and `Footer.astro` are net-new, so a destination read isn't required (but is harmless if the scaffold happens to ship them).
+
+### Token contract (do this first — it gates everything)
+
+Map the Designer's `designTokens` into the `@theme` palette that goes in `global.css`, and **guarantee every required token resolves**. Per `STYLING.md` § "Required tokens", the `components-<pack>.css` templates reference a fixed set via `var(--token)`. Your `@theme` MUST declare all of:
+
+- `--color-{paper,paper-warm,ink,mute,rule,accent}` (required), `--color-{ink-soft,cream,error}` (recommended).
+- `--font-{display,body}`.
+- the full `--spacing-{2xs,xs,sm,md,lg,xl,2xl,3xl,4xl}` scale.
+- `--radius-{sm,md}` (required), `--radius-{lg,xl}` (recommended).
+- a **container scale** separate from spacing: `--container-{prose,md,3xl,6xl}` minimum.
+
+If the Designer's spec is missing a required role, **derive** a sensible value (e.g. `ink-soft` ≈ `ink` lightened, `paper-warm` ≈ `paper` warmed) rather than dropping the token — a missing required token renders components unstyled. Map each group with the fixed prefix: `colors.<k>` → `--color-<k>`, `fonts.<k>` → `--font-<k>`, `spacing.<k>` → `--spacing-<k>`, `radii.<k>` → `--radius-<k>`, `containers.<k>` → `--container-<k>`.
+
+> **Container ≠ spacing.** Tailwind v4 maps `max-w-3xl` → `var(--container-3xl)`, not `var(--spacing-3xl)`. Never set a `--container-*` to a spacing value — a reading column is ~`42rem`, not `5rem`, or pages collapse to one word per line.
+
+### 1. `global.css`
+
+Substitute the `{{theme}}` block in the skeleton with the `@theme` palette you built above — every `--color-*`, `--font-*`, `--spacing-*`, `--container-*`, `--radius-*` line. **Everything else in the skeleton is literal** (the `@utility container-reading`/`btn`, base layer, button family, decorative + site-shell + view-transition + nav-submenu + category-rail CSS). Do not add component-specific classes (`.product-card`, `.cart-summary`, …) — those live in `components-<pack>.css`, owned by Phase 3.
+
+### 2. `astro.config.mjs`
+
+This is a **merge, not a clobber** — the scaffold's config varies. Read the scaffold's `astro.config.mjs` and apply exactly two mutations (the skeleton shows the target shape):
+1. Register the Tailwind v4 Vite plugin: `import tailwindcss from "@tailwindcss/vite";` and merge `tailwindcss()` into `vite.plugins` (preserve any existing `vite` settings — `server.allowedHosts`, etc.).
+2. Fix the bare `process.env` line (`const isBuild = process.env.NODE_ENV == "production";`) to the `globalThis` guard so strict `tsc --noEmit` passes without `@types/node`.
+
+### 3. `Layout.astro`
+
+Fully replace the scaffold stub. Substitute:
+- `{{components-css-imports}}` — one `import '../styles/components-<pack>.css';` per pack in **"Packs with components"**, in that order. Packs without components (e.g. `cms`) get **no** import — importing a file no agent writes breaks the build. If "Packs with components" is empty, remove the placeholder line entirely.
+- `{{fonts.googleHref}}` — the Google Fonts stylesheet href for the chosen `display` + `body` families (e.g. `https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@...&family=Inter:wght@400;500;600&display=swap`). If both fonts are system fonts, remove the `<link rel="stylesheet">` line.
+- `{{brand.name}}` — the default `<title>`.
+
+The View-Transitions `<script>`, the `nav-progress` div, the `ClientRouter`, the `Props` interface, and the `hasSeoTags` pattern are **literal** — keep them.
+
+### 4. `Navigation.astro`
+
+Substitute `{{shell.navBrandMark}}` and `{{nav.links}}` (one `<li class="site-nav-item"><a href={href}>{label}</a></li>` per inlined nav link, labels **verbatim** — no editorial rebrands like "Journal" for `/about`). Keep the `<!-- nav:links -->` marker, the empty `<div class="nav-actions">`, the `transition:persist`, and the hamburger literal. Do **not** add `/products`, cart, login, or account links — packs splice those at the marker in Phase 4.
+
+### 5. `Footer.astro`
+
+Substitute `{{brand.name}}`, `{{shell.footerTagline}}`, and `{{nav.links}}` (mirror/subset of the same array, labels verbatim). Keep `transition:persist` literal.
+
+### 6. `index.astro`
+
+Substitute `{{shell.heroHeadline}}`, `{{shell.heroSub}}`, `{{brand.name}}`, and `{{home-markers}}`. For `{{home-markers}}`, emit one `<!-- home:<pack> -->` marker per **loaded pack that contributes a home section** (today: `stores`, `gift-cards`). Emit a marker **only** for such packs — never one no pack will fill (no `<!-- home:cms -->`; CMS owns brand-story directly, which the skeleton already renders). Keep the hero + brand-story structure and both `data-decorative-slot` placeholders literal and **empty** (the orchestrator injects `<img>` after Image Phase 1).
+
+## Disabled-pack discipline
+
+A pack in **"Disabled packs"** (today: only `gift-cards`) ships dormant. Its `<!-- home:<pack> -->` / `<!-- nav:links -->` markers are the **only** acceptable touchpoints. Do **not** add hero CTAs, footer links, brand-story callouts, or any other entry point pointing at a disabled pack's route — users click through to a feature that does not exist yet. Treat disabled packs as code-only: they appear in your marker emission, never in visible UI you author.
+
+## Self-checks before returning
+
+1. **Component-CSS imports.** For every pack in "Packs with components", grep your written `Layout.astro` for `components-<pack>.css`. If any is missing, add it. If unrecoverable, return `status: "partial"` with `errors: [{code: "MISSING_COMPONENT_CSS_IMPORT", pack: "<name>"}]`. (The orchestrator also re-verifies this after you return — at the seed gate — but catch it here.)
+2. **Required-token coverage.** Confirm every required token from the contract above is present in the `@theme` block you wrote. A missing one renders components unstyled.
+3. **Container vs spacing.** Confirm no `--container-*` was set to a spacing value.
+4. **Marker hygiene.** No marker emitted for a pack that does not contribute; both decorative slots present and empty.
+
+If a check fails and you cannot fix it, return `status: "partial"` with the specific `errors` code rather than shipping silently.
+
+## Return contract
+
+A single fenced JSON block per `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`, last content in your message — a manifest of what you wrote:
+
+```json
+{
+  "status": "complete",
+  "phase": "compose",
+  "data": {
+    "filesWritten": [
+      "src/styles/global.css",
+      "astro.config.mjs",
+      "src/layouts/Layout.astro",
+      "src/components/Navigation.astro",
+      "src/components/Footer.astro",
+      "src/pages/index.astro"
+    ],
+    "componentCssImports": ["stores", "ecom"],
+    "homeMarkers": ["home:stores"],
+    "tokensApplied": { "colors": 9, "spacing": 9, "containers": 4, "radii": 2, "fonts": 2 }
+  },
+  "files": [ "...same as filesWritten..." ]
+}
+```
+
+No trailing prose after the closing fence.
+
+## Anti-patterns
+
+| WRONG | CORRECT |
+|---|---|
+| Re-author the View-Transitions script, btn family, or view-transition CSS | Keep the skeleton bulk literal; substitute only `{{…}}` slots |
+| Rewrite `global.css` from scratch to "clean it up" | Substitute `{{theme}}`; the rest is pinned (this is the variance win) |
+| Overwrite `astro.config.mjs` with the skeleton verbatim | Merge the two mutations into the scaffold's own config |
+| `import '../styles/components-cms.css'` (cms has no components) | One import only per pack in "Packs with components" |
+| Drop a required token because the Designer omitted it | Derive a sensible value — required tokens must resolve |
+| Set `--container-3xl` to `--spacing-3xl`'s value | Containers are widths (~`42rem`+), a separate axis from spacing |
+| Coin label rebrands ("Journal" → /about) or add `/products`/cart links | Nav labels verbatim; packs splice their links at the marker |
+| Add a hero CTA / footer link to a disabled-pack route | Disabled packs are code-only — markers are the sole touchpoint |
+| Emit `<!-- home:cms -->` or a marker for a non-contributing pack | One marker per contributing loaded pack only |
+| `Read <SKILL_ROOT>/references/astro/templates/` (the directory) | `EISDIR` — Read each of the six skeletons by its exact file path (batch the six Reads); `Glob` if you must discover them |
+| `Read .wix/site.json` for brand/tokens | Every input is inlined in your prompt |
+| Branch to a non-astro / custom frontend | astro only; return `FRONTEND_NOT_SUPPORTED` otherwise |

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

@@ -296,4 +296,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`