@wix/agent-skills 1.5.0 → 1.7.0

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

@@ -1,6 +1,71 @@
 # Discovery
 
-Infer as much as possible from the user's opening message; ask only what's genuinely unknown. Target: **~1:30 of discovery** including user think-time.
+Capture brand + vibe + imagery + the per-vertical intent inferred from the user's prompt, present a slim plan, get approval, write `.wix/site.json`.
+
+Infer as much as possible from the user's opening message; ask only what's genuinely unknown. Target: **~1:30 of discovery** including user think-time, **≤ 80 s** excluding it.
+
+This phase owns the *domain* of discovery only. Run FLOW — when background work is dispatched, what waits on what, batching, and the transition into Setup/Seed — is owned by `references/PLAN.md` (pre-approval) and `references/BUILD.md` (post-approval).
+
+## Wave 0 — Mode detection (BEFORE any user-facing question)
+
+Frontend mode is the single axis the frontend track branches on. Detect it from the working directory **first** — before the CLI-auth pre-flight, before Q1 — so the rest of Discovery knows which path to take. The detection is a file-existence check; cost is ~1 ms. The axis is binary: **astro (supported) vs custom (anything else, not available yet).**
+
+```
+Inspect CWD:
+
+1. CWD is empty (or doesn't exist) → SCAFFOLD MODE (astro).
+2. CWD contains `wix.config.json` AND Astro structure (`src/`, `astro.config.mjs`)
+   → resume a prior wix-headless run. See SKILL.md § "When NOT to use this skill"
+     ("continue or start fresh?" — out of pivot scope).
+3. CWD contains `wix.config.json` AND a non-Astro frontend (e.g. `index.html` at
+   root, `*.jsx`/`*.tsx`/`*.vue` files) → CUSTOM (non-astro), not available yet.
+4. CWD contains source files (`index.html`, `*.jsx`, `*.tsx`, `*.vue`,
+   `package.json` from a non-Wix template, etc.) AND no `wix.config.json`
+   → CUSTOM (non-astro), not available yet.
+```
+
+Capture the resolved value in session scratch as `frontend`:
+
+| Scenario | `frontend` value | Wave 0 next |
+|---|---|---|
+| Scaffold mode (empty CWD) | `astro` | Continue to Pre-flight below |
+| Prompt names a non-astro frontend (Vite, React SPA, etc.) | `custom` | Route to the custom stub — see § "Custom (non-astro) — not available yet" below |
+| Existing project detected (cases 3 & 4 above) | `custom` | Route to the custom stub — see § "Custom (non-astro) — not available yet" below |
+
+> **No `AskUserQuestion` for mode detection.** Mode is detected, never asked. If the working directory is ambiguous, default to `custom` and let the not-available message redirect the user (they can re-run with an empty directory for the astro path).
+
+`frontend` flows into three places:
+- `scaffold.sh --frontend <value>` — the scaffolder's input (only `astro` is built; custom does not scaffold — see § "Custom (non-astro) — not available yet").
+- `init-site-json.mjs --frontend <value>` — "After Approval" § 2 (records it in the slim site.json snapshot; only reached on the astro path).
+- Orchestrator session scratch — every downstream branch reads the scratch value, not the file: the frontend-track project-prep script (`seed-utilities.sh --template astro`) and the SEED Layout-import bridge. (Business-track steps — app install, seeders — never read it.)
+
+## Custom (non-astro) — not available yet (when `frontend === "custom"`)
+
+Custom frontends are **not available yet** — astro is the only supported frontend. Do **not** run the interview, scaffold, Designer, Setup, or Seed. Open `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`, surface its not-available message to the user, and **stop**:
+
+> *Custom (non-astro) frontends are not available yet — astro is the supported frontend. Re-run with the astro frontend (start from an empty directory), or check back later.*
+
+No `.wix/site.json` is written and no `BUILD.md` flow runs. The intended future shape for the custom track (init scaffold + shared business track + per-pack SDK wiring) is recorded in `references/custom/INSTRUCTIONS.md` § "Intended future shape"; the retired Integrate (Path B) flow in `SETUP.md` is its historical reference. See `PLAN.md` § "Custom (non-astro) frontends — not available yet" for the routing.
+
+---
+
+## Pre-flight — Verify CLI auth (BEFORE any user-facing question)
+
+The first Wix touch is the post-approval scaffold (`scaffold.sh` → `npm create @wix/new@latest headless`), which creates a business + project against the user's Wix account and so requires an active CLI session. Without one it fails — and because the scaffold now runs **after** approval (`BUILD.md` run-step 0), a logged-out user wouldn't find out until they'd done the whole interview *and* approved, only to have the build fail immediately. Run the auth check foreground here so a logged-out user sees the login prompt before any `AskUserQuestion`.
+
+```bash
+npx @wix/cli@latest whoami >/dev/null 2>&1
+```
+
+- Exit 0 → continue to Step 0.
+- Exit non-zero → **run `npx @wix/cli@latest login` yourself; do NOT punt to the user.** Steps:
+  1. `Bash` tool with command `npx @wix/cli@latest login`, `run_in_background: true`. No shell `&`, no `mktemp` redirect, no chaining.
+  2. Read the harness output-file path from the tool reply's `<bash-stdout>` (or use `TaskOutput`).
+  3. Parse line 1 for `{"event":"awaiting_user","userCode":"…","verificationUri":"…"}` (ignore any `TimeoutNaNWarning` on later lines).
+  4. Surface in one plain-prose message — *not* `AskUserQuestion`: *"Open `<verificationUri>` in your browser and enter the code `<userCode>` — I'll continue once you've completed the login."*
+  5. Wait for the harness `task-notification` with `<status>completed</status>`; confirm with `whoami`, then proceed to Step 0.
+
+  Full recovery reference: [`shared/AUTHENTICATION.md`](shared/AUTHENTICATION.md#wix-login-from-a-non-interactive-agent).
 
 ## Step 0 — Infer Vertical(s) and Business Context
 
@@ -35,57 +100,40 @@ If the user picks *"Type my own"*, follow up conversationally: *"Sure — what s
 
 If the user already named the brand in the opening message, skip this step.
 
-### Background actions on Q1 answer
+### After Q1 — read the loaded pack files; scaffold inputs
 
-Immediately after the brand name is confirmed (before Q2), emit **one concurrent batch** containing both the scaffold dispatch AND prefetch reads of the shared contract docs. These reads cost nothing during Q2 + plan review wait time but save ~1 min of post-approval latency that prior runs spent reading these docs serially.
+Once the brand is confirmed, read the loaded pack contents (to compose the plan) and prepare the scaffold inputs (slug + frontend value) for later. **The scaffold is NOT dispatched during Discovery** — it is dispatched post-approval (`BUILD.md` run-step 0), so the funnel can present the plan without waiting on anything. This section defines only the slug derivation + the `scaffold.sh` command shape.
 
-1. **Scaffold dispatch.** Derive the project slug from the brand, validate it, then run `bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>"` as a background shell. The script handles the npm-create invocation + slug pre-flight (regex `^[a-z0-9]{3,20}$`); the orchestrator handles slug derivation from the human-readable brand.
+**(a) Read every pack in the resolved set.** The full resolved set lives in SKILL.md § "When this skill triggers" (third column). For example, a `stores` run reads four files: `stores.md`, `cms.md`, `ecom.md`, `gift-cards.md`. Read the whole resolved set at once — do **not** read the top-level pack alone, then discover its `requires:` and issue a second batch.
 
-   **Slug derivation (apply to brand before invoking the script):**
-   1. Lowercase
-   2. Strip every char that isn't `[a-z0-9]` (drop hyphens, spaces, punctuation, accents — the Wix CLI rejects them)
-   3. Truncate to 20 chars
-   4. If the result is shorter than 3 chars, ask the user explicitly for a slug (`AskUserQuestion`)
+- `Read <SKILL_ROOT>/references/verticals/<pack>.md` for each pack in the resolved set (resolve `<SKILL_ROOT>` per SKILL.md § "Path resolution"). Read individual `.md` files; `Read` on the directory returns `EISDIR`.
 
-   Examples: `"Acme-Co" → "acmeco"`; `"Sole Society" → "solesociety"`; `"E&E Co." → "eeco"`; `"AB" → ask the user`.
+These reads pre-load the `routes:`, `apps:`, `requires:`, and `disabled` fields needed to compose the Pages table at Step 3.
 
-   The Wix CLI requires `[a-z0-9]{3,20}` — hyphens, underscores, uppercase, and other punctuation are rejected.
+**(b) The scaffold inputs.** The scaffolder is invoked as:
 
-   **Pre-flight validation (orchestrator-side, before invoking the script).** Both must pass; if either fails, regenerate the slug or re-prompt the user — do NOT rely solely on the script's pre-flight (it'll exit non-zero, but that costs a round-trip):
-   - `slug` matches `^[a-z0-9]{3,20}$`
-   - `brand` is non-empty after trimming whitespace
+```bash
+bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<brand>" --frontend <frontend> 2> <tempfile>
+```
 
-   **The scaffold call (background shell, with timing capture):**
+`<frontend>` is `astro` — the only supported (and only scaffolded) frontend. The scaffold step is reached only on the astro path; a custom frontend never gets here, because Wave 0 routes it to the stub before Q1 (§ "Custom (non-astro) — not available yet"). If the opening prompt explicitly names a non-astro frontend (Vite / React SPA / etc.), Wave 0 already set `frontend = "custom"` and short-circuited — this step does not run.
 
-   ```bash
-   STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-   bash "<SKILL_ROOT>/scripts/scaffold.sh" "<slug>" "<brand>"
-   ENDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-   ```
+**Slug derivation:** lowercase the brand, then **STRIP every character not matching `[a-z0-9]` — do NOT replace them with hyphens or underscores**. Truncate to 20 chars. The `scaffold.sh` pre-flight enforces `^[a-z0-9]{3,20}$` and rejects anything else with exit 2; a rejected slug forces a re-run of the ~30 s scaffold (the indie-bookshop-class regression).
 
    - Substitute `<brand>` with the user's confirmed brand (preserve original case; quotes are passed by the shell). Substitute `<slug>` with the validated slug.
-   - The script pins `--site-template-id` to the pure-headless blank template (`212b41cb-0da6-4401-9c72-7c579e6477a2`). Vibe-compatible templates trigger an interactive prompt that blocks non-TTY runs — the template ID is intentionally hardcoded inside the script.
+   - The script passes bare `--site-template` so non-interactive scaffolding stays on the blank starter. Keep the new-site flow there unless the skill is explicitly redesigned around another scaffold. (Without it, `@wix/create-new` ≥0.0.72 prompts for a template and aborts in the agent's non-TTY shell.)
    - Append timing to `.wix/run.json.phases[]` as `{ phase: "scaffold", seconds: <duration>, started: $STARTED_AT, ended: $ENDED_AT }`.
 
-   **Strict-then-recover:**
-   1. Script exit 2 (slug or brand validation failed) → orchestrator-side bug; the orchestrator should have caught this in pre-flight. Fix the slug derivation and retry.
-   2. Auth error from npm/Wix CLI → surface `"Run \`npx @wix/cli login\` and retry."` and stop.
-   3. `invalid template` error → the template ID inside `scaffold.sh` is stale. Look up the current ID via `<prefix>SearchWixCLIDocumentation` query `create headless template`, edit the script's `TEMPLATE_ID` constant, retry once, log to `.wix/run.json.commandDrift[]` so the script can be tightened.
-   4. Other errors → surface stderr to the user.
-
-   Launch with background.
-
-2. **Prefetch shared contracts** — siblings in the same concurrent batch (resolve `<SKILL_ROOT>` per SKILL.md § "Path resolution"):
-   - `Read <SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`
-   - `Read <SKILL_ROOT>/references/shared/IMAGE_GENERATION.md`
-   - `Read <SKILL_ROOT>/references/shared/MCP_PREFIX.md`
+Correct (strip-and-concatenate):
+- `"Bloom & Root"` → `"bloomroot"` (not `"bloom-and-root"`, not `"bloom-root"`)
+- `"Page & Ember"` → `"pageember"` (not `"page-ember"`, not `"page-and-ember"`)
+- `"ACME, Co."` → `"acmeco"`
+- `"42 Below"` → `"42below"`
+- `"Single-Origin Roasters"` → `"singleoriginroasters"` (cap at 20 → `"singleoriginroaster"` if truncation needed)
 
-3. **Prefetch loaded pack files** — siblings in the same message:
-   - `Read <SKILL_ROOT>/references/verticals/<pack>.md` for each loaded pack
+**Wrong** (kebab-case / snake-case): any slug containing `-`, `_`, or any other separator. The transformation is **strip**, not **replace** — there are no separators in a valid slug.
 
-Then continue to Q2. The scaffold runs during Q2 + plan review (~30–60s, usually finishes before approval); the reads resolve near-instantly and pre-load the docs the orchestrator needs at Step 3 and Step 7, eliminating mid-flow read churn.
-
-**Do NOT also prefetch these docs after plan approval.** Reading them between plan approval and Step 3 adds ~1 min of user-visible wait with zero overlap to useful work.
+Then continue to Q2.
 
 ---
 
@@ -103,6 +151,90 @@ Example options for a jewelry store:
 
 If the user picks "Something else", follow up with `AskUserQuestion` using a text input.
 
+---
+
+## Step 2.5 — Imagery preference
+
+Before crafting the aesthetic direction and presenting the plan, capture the user's imagery preference. Hold this `imagery` flag in orchestrator session scratch — it gates whether downstream phases generate AI imagery (Wix AI credits) or rely on CSS-only themed blocks. The flag is **not** persisted to `.wix/site.json`; the orchestrator inlines it into the prompts of any subagent that needs to branch on it (Image Phase 1 dispatch, Image Phase 2 gate).
+
+**Skip rule.** If the user's opening prompt explicitly mentioned imagery — phrases like *"with photos"*, *"with images"*, *"AI imagery"*, *"product photos"*, *"with pictures"* — skip the Q3 `AskUserQuestion` call and default `imagery` to `"ai-generated"`. Re-asking would feel redundant ("you already said you wanted images"). The credit estimate (§ 2.5.1) and balance fetch (§ 2.5.2) still run so the captured intent has the right numbers for the plan's Imagery line — only the `AskUserQuestion` itself is skipped.
+
+### 2.5.1 — Compute the credit estimate
+
+In session scratch, compute `<estimatedCredits>` from the loaded packs and the per-vertical intent inferences (see "After Approval" § 1 for the inference rules — `productCount` defaults to 3, `postCount` defaults to 6).
+
+```
+estimatedCredits =
+    1                                          // hero / home decorative
+  + 2                                          // additional section decoratives
+  + (cms loaded         ? 2                              : 0)   // /about + /faq hero images
+  + (stores loaded      ? stores.productCount            : 0)   // default 3 when unknown
+  + (blog loaded        ? blog.postCount                 : 0)   // default 6 when unknown
+  + (forms loaded       ? 0                              : 0)   // forms never trigger imagery
+  + (gift-cards loaded  ? 0                              : 0)   // disabled pack — skip
+```
+
+Packs with `disabled: true` contribute 0 regardless. The integer total is what we show. **Reuse** the `productCount=3` and `postCount=6` defaults from "After Approval" § 1 — do not invent new numbers.
+
+Worked examples:
+- Skincare (stores + cms, productCount=3, no blog): `1 + 2 + 2 + 3 + 0 + 0 + 0 = 8`.
+- Coffee shop (stores + cms + blog, productCount=3, postCount=6): `1 + 2 + 2 + 3 + 6 + 0 + 0 = 14`.
+
+### 2.5.2 — Fetch the AI-credit balance
+
+`npx @wix/cli@latest token` **without** `--site` mints an **account-scoped** token. With that token, the balance endpoint at `POST https://manage.wix.com/credit-transactions/v1/credit-transactions/get-account-balance` returns the current periodic credit balance + cap.
+
+```bash
+ACCOUNT_TOKEN=$(npx @wix/cli@latest token)   # NO --site — mints account-scoped
+curl -sS -X POST \
+  -H "Authorization: Bearer $ACCOUNT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}' \
+  "https://manage.wix.com/credit-transactions/v1/credit-transactions/get-account-balance"
+```
+
+Successful response (HTTP 200):
+```json
+{
+  "periodicCredits": { "balance": 250, "cap": 250 },
+  "creditBalanceBreakdown": [
+    { "subscriptionId": "…",
+      "usageRules": [{ "period": "MONTH", "balance": 250, "cap": 250, "resetDate": "…" }] }
+  ]
+}
+```
+
+Hold `balance = response.periodicCredits.balance` and `cap = response.periodicCredits.cap` in scratch.
+
+**Recovery / fallback (in order):**
+
+1. **`wix token` (no `--site`) fails** — surface the error from the CLI; that is a `wix login` problem, not a balance-lookup problem. Set `balance = null` only after the CLI failure surfaces.
+2. **POST returns 401/403** — the **account-scoped** token (no `--site`) was rejected. Re-mint the account-scoped token once and retry. (The site-scoped "never re-mint" rule in `SEED.md` / `SETUP.md` does not apply here — these are distinct token caches.) If still 401/403, set `balance = null` and proceed.
+3. **POST returns 4xx other than 401/403** — log the response in scratch (do not crash) and set `balance = null`. The endpoint is POST-only; a GET returns 400.
+4. **Network error / timeout** — set `balance = null`. The credit estimate (§ 2.5.1) is unaffected; only the Q3 description's *"Current balance: …"* tail goes silent.
+
+> **Don't share the token across calls.** The account-scoped token is for account-level reads only (balance, account metadata). Every other site-operating call in this skill uses `npx @wix/cli@latest token --site "$SITE_ID"` — site-scoped — per `references/shared/AUTHENTICATION.md`. Site-scoped tokens are rejected by the account endpoint and vice-versa.
+
+### 2.5.3 — Ask Q3
+
+Ask **Q3** via `AskUserQuestion` with two single-select options. Interpolate `<estimatedCredits>` (from § 2.5.1) and the balance (from § 2.5.2) into the AI-generated `description:` before issuing the call.
+
+> *"How should we handle imagery?"*
+
+Options:
+- **Themed blocks (Recommended)** — `description:` *"Polished CSS-only design. ~6 min build. Uses 0 Wix AI credits."*
+- **AI-generated imagery** — `description:` *"Bespoke images per product and section. ~10 min build. Uses ~<estimatedCredits> Wix AI credits (1 image = 1 credit). Current balance: <balance> / <cap>."*
+
+If `balance === null`, drop the trailing *"Current balance: …"* sentence entirely (do not print *"Current balance: unknown"* — silence is the contract). The AI-generated option then reads: *"Bespoke images per product and section. ~10 min build. Uses ~<estimatedCredits> Wix AI credits (1 image = 1 credit)."*
+
+→ **Verify Q3:** Themed blocks description ends `Uses 0 Wix AI credits.`. AI-generated description contains the substring `Uses ~<estimatedCredits> Wix AI credits (1 image = 1 credit).` (with `<estimatedCredits>` replaced by the integer). When balance is known, description also ends with `Current balance: <balance> / <cap>.`. When balance is unknown, description ends with `(1 image = 1 credit).` and no balance text follows.
+
+Capture the answer as `imagery: "themed-blocks" | "ai-generated"` in session scratch. The downstream dispatch gates that consume it are owned by `BUILD.md § "Imagery gates"`.
+
+The captured `imagery` value lives in orchestrator session scratch (alongside the inferred per-vertical intent — see "After Approval" § 1). It is **not** written to `.wix/site.json`; subagents that need to branch on it receive it inlined in their prompts.
+
+---
+
 ### Craft the aesthetic direction (in session scratch)
 
 Based on vertical + brand personality + audience, craft a **2–3 sentence aesthetic direction** like a designer would. Decide — don't ask more questions.
@@ -114,19 +246,32 @@ Example:
 
 ---
 
+## The Designer's inputs
+
+The Designer owns **the design itself** — it returns a framework-agnostic JSON spec (tokens + brand-voice strings) and **writes no files**. It is framework-blind and application-blind by construction, so its inputs are *judgment* inputs only, and they are all produced here in Discovery and held in scratch:
+
+- **Brand**: `{ name, description }` from Q1 (description = the user's opening business context, distilled to one line).
+- **Aesthetic direction, color palette, typography, mood, page color strategy**: from the craft step above.
+
+The application inputs (loaded packs, packs-with-components, disabled packs, navigation links) are **not** passed to the Designer — they go to the **Composer**. Hold them in scratch too, but for the Composer prompt in SEED. (Nav-links example for stores+cms+ecom+gift-cards: `[{"href":"/about","label":"About"},{"href":"/faq","label":"FAQ"}]` — `/about` + `/faq` when `cms` is loaded; never `/products` (stores splices it), `/gift-cards` (disabled), or any route whose pack contributes a nav marker.)
+
+The orchestrator dispatches the Designer with these inputs **post-approval** (`BUILD.md` run-step 0) — not during Discovery; the Designer's prompt template lives in `DESIGN_SYSTEM.md`. Discovery only produces and holds the inputs in scratch.
+
+---
+
 ## Step 3 — Present the Plan
 
-Present the plan as formatted markdown. After presenting, use `AskUserQuestion` for approval.
+**Send the rendered plan as its own assistant message FIRST** — the full formatted markdown (Sections A/B/C + Imagery line) that the user reads. **Only then, as a separate step, use `AskUserQuestion` for approval.** Never bundle the plan into the approval question, never replace it with a one-line "here's the plan", and never skip straight to "Ready to build?" — the user must see the rendered plan before the question. (This is the only thing between Q&A and approval; there is nothing else to do here — see `PLAN.md` § "Wave 0".)
 
-> **Do NOT show implementation details.** Users do not want to read about scaffolding, `npm install`, `env pull`, MCP calls, phase agents, designer handoffs, sidecars, or build/preview steps. They care about their site. The TaskList conveys progress; the plan conveys outcome. Never open with SDK packages or CMS collection fields.
+> **Do NOT show implementation details.** Users do not want to read about scaffolding, `npm install`, `env pull`, API calls, phase agents, designer handoffs, sidecars, or build/preview steps. They care about their site. The TaskList conveys progress; the plan conveys outcome. Never open with SDK packages or CMS collection fields.
 
-The plan is composed from the loaded vertical packs. Each pack contributes: apps, packages, pages, CMS collections, features blurbs. The skill assembles; the packs supply.
+The plan is composed from the loaded vertical packs. Each pack contributes: pages and features blurbs. The skill assembles; the packs supply. **Apps, packages, and CMS collection names are implementation details** — not surfaced in the plan; the loaded verticals determine apps to install and the seeder names CMS collections at run time.
 
 ### Plan structure (in order)
 
-The plan has TWO halves: a short **decision card** (Sections A + B — what the user actually weighs in on) and a longer **technical scope** block (Sections C + D + E — what comes "for free" from the loaded packs). The user reads A and B carefully; C–E are reference material they skim or skip.
+The plan has TWO halves: a short **decision card** (Sections A + B — what the user actually weighs in on) and a tighter **technical scope** block (Section C + Imagery line — what comes "for free" from the loaded packs). The user reads A and B carefully; C is reference material they skim or skip.
 
-> **Sections C, D, E are markdown tables.** Each section below leads with the exact header skeleton — copy it verbatim. Do NOT type column headers from memory: that's the root cause of every plan-format regression.
+> **Section C is a markdown table.** It leads with the exact header skeleton — copy it verbatim. Do NOT type column headers from memory: that's the root cause of every plan-format regression.
 
 **Section A: Design Direction** — Lead with this. Open with the aesthetic paragraph crafted in Step 2, then a compact detail block:
 - Aesthetic tone (e.g., "organic editorial")
@@ -192,57 +337,15 @@ Source cell:
 
 ---
 
-**Section D: CMS Collections.** Emit exactly this header, then one row per `cmsCollections:` entry from each loaded pack:
+**Imagery line.** A single line below Section C, not a table:
 
 ```
-| Collection | Key Fields |
-|------------|------------|
+**Imagery:** Themed blocks
 ```
 
-> **STOP if you typed `Fields` instead of `Key Fields`.** Re-read the skeleton above.
+…or `**Imagery:** AI-generated (~<estimatedCredits> Wix AI credits)` when Q3 captured `ai-generated`, with `<estimatedCredits>` replaced by the integer computed in Step 2.5 § 2.5.1. Copy the imagery value from the captured preference; the credit count is the same number shown to the user at Q3. **Do not** repeat the current balance here — it was already shown at Q3, and re-printing it in Section C clutters the reference table the user skims.
 
-Iterate `cmsCollections:` from each loaded pack and emit one row per collection (collections from the `cms` pack always appear; other packs may declare their own).
-
-→ **Verify D:** Header is exactly `| Collection | Key Fields |`.
-
----
-
-**Section E: Apps & SDK Packages.** Last. Reference table for developer-minded users. Emit exactly this header, then **one row per loaded pack** (NOT one row per package):
-
-```
-| App | SDK Packages |
-|-----|--------------|
-```
-
-> **STOP if you wrote one row per package.** `| Item | Type |` with `@wix/stores | SDK`, `@wix/ecom | SDK`, … is the wrong shape. Two columns, comma-joined packages in cell two, **one row per App**, not per SDK. Re-read the skeleton above.
-
-**Compose Section E from loaded pack frontmatter:**
-
-```
-A pack contributes a Section E row iff:
-  - Its `apps:` array is non-empty (top-level user-facing app), OR
-  - Its `include: true` (the cms pack — built-in, no app to install).
-
-The "App" cell:
-  - For packs with non-empty `apps:`: apps[0].name (e.g. "Wix Stores").
-  - For the cms pack: the literal "CMS (builtin)".
-
-The "SDK Packages" cell:
-  - This pack's `packages:` ∪ packages from every pack in its transitive
-    `requires:` chain — deduped, in declared order.
-  - So when stores is loaded (and pulls in ecom + gift-cards via requires),
-    the "Wix Stores" row's SDK Packages cell is the union of stores +
-    ecom + gift-cards packages — typically: @wix/stores, @wix/ecom,
-    @wix/redirects, @wix/site, @wix/essentials.
-
-Packs with `apps: []` AND `include: false` (ecom, gift-cards) do
-NOT get their own row. Their packages roll up under whichever loaded
-top-level pack pulled them in. There is no "@wix/gift-cards" SDK on
-npm; the gift-cards pack is runtime-detected via REST and contributes
-zero npm packages of its own.
-```
-
-→ **Verify E:** Header is exactly `| App | SDK Packages |`. One row per loaded pack with non-empty `apps:` OR `include: true`. SDK Packages cell is comma-joined within a single cell, NOT split across rows. No "Wix Gift Cards" row when gift-cards loads transitively (no `@wix/gift-cards` SDK exists).
+→ **Verify Imagery:** Exactly one line. If themed: value is `Themed blocks`. If AI-generated: value matches `^AI-generated \(~\d+ Wix AI credits\)$`. No second line, no table, no other commentary.
 
 ### Example (skincare ecommerce brand)
 
@@ -286,19 +389,7 @@ tactile and approachable.
 | Thank You      | /thank-you        | Wix Stores    |
 | Checkout       | Hosted by Wix     | Wix Stores    |
 
-## CMS Collections
-
-| Collection     | Key Fields                  |
-|----------------|-----------------------------|
-| About Content  | heading, body, image        |
-| FAQ            | question, answer, sortOrder |
-
-## Apps & SDK Packages
-
-| App           | SDK Packages                                                       |
-|---------------|--------------------------------------------------------------------|
-| Wix Stores    | @wix/stores, @wix/ecom, @wix/redirects, @wix/site, @wix/essentials |
-| CMS (builtin) | @wix/data, @wix/essentials                                         |
+**Imagery:** Themed blocks
 
 Should I proceed?
 ```
@@ -307,7 +398,7 @@ The Cart, Thank You, and Checkout rows show `Source: Wix Stores` — not "Wix eC
 
 ### Final scan (MANDATORY)
 
-Before sending the plan, confirm each inline → Verify above (B, C, D, E) passed. If any failed, regenerate that section and re-scan before emitting. Plans that violate multiple inline checks at once cost a full plan replay (~25 min of user time) when caught post-hoc. The inline → Verify lines exist to catch them before sending.
+Before sending the plan, confirm each inline → Verify above (B, C, Imagery) passed. If any failed, regenerate that section and re-scan before emitting. Plans that violate multiple inline checks at once cost a full plan replay (~25 min of user time) when caught post-hoc. The inline → Verify lines exist to catch them before sending.
 
 ### Approval
 
@@ -317,16 +408,50 @@ If the user wants to adjust, handle it conversationally (swap brand, change vibe
 
 ---
 
-## After Approval
+## After Approval — capture intent in scratch and write `.wix/site.json`
 
-Save the project context to memory (type: `project`) so future sessions can resume:
-- Brand name, vertical(s) inferred
-- Apps, packages, pages from the loaded packs
-- Project name + absolute project directory
-- Current phase: `scaffolding`
+On the user's "Yes, build it" approval, hold the captured intent in orchestrator session scratch and write a slim `.wix/site.json` metadata snapshot. The transition into Setup — and what Setup synchronizes on — is FLOW, owned by `PLAN.md` (which hands off to `BUILD.md` on approval).
 
-> **Do NOT narrate the internal sub-steps.** After approval, proceed silently through setup, launch phases, etc. The user tracks progress via TaskList — that's enough. No *"Now I'll install Wix Stores via MCP"*, no *"Launching Phase 1 agents"*, no MCP / sidecar / agent-name / `.wix/` leakage.
+### 1 · Compose the intent block in session scratch
+
+In session scratch, build a single JSON object carrying the captured imagery flag plus per-vertical hints inferred from the user's prompt. Only include blocks for verticals that were loaded. This stays in orchestrator memory for the rest of the run — it is **not** written to disk. Seeders receive the relevant `intent.<pack>` slice inlined in their prompts (see `SEED.md` Step 2).
+
+```json
+{
+  "imagery": "themed-blocks",
+  "stores":     { "productCount": 3, "categoriesNamed": ["..."] },
+  "cms":        { "collections": [{ "purpose": "about", "itemCount": 1 }] },
+  "blog":       { "postCount": 6, "topics": ["..."] },
+  "forms":      { "forms": [{ "purpose": "contact", "fields": ["..."] }] },
+  "gift-cards": { "enabled": true }
+}
+```
+
+Inference guidelines for each block:
+- **`imagery`** — exactly the value captured at Step 2.5. If the user picked `"ai-generated"`, still pass `"ai-generated"` here; the AI-imagery fallback messaging happens in the user-facing summary, not in the captured intent.
+- **`stores.productCount`** — number of products the user implied (e.g. *"a few candles"* → 3, *"a full catalog"* → 8). When unclear, default to 3.
+- **`stores.categoriesNamed`** — strings the user explicitly named (*"a section for soaps and one for candles"* → `["Soaps", "Candles"]`). Empty array if none named.
+- **`cms.collections`** — one entry per CMS-driven page: at minimum `{purpose: "about"}` and `{purpose: "faq"}` for any cms-loaded run. `itemCount` only when the user implied a number (*"a 5-question FAQ"* → `itemCount: 5`).
+- **`blog.postCount`** — count the user implied; default to 6 when unclear. **`topics`** are explicit-only.
+- **`forms.forms`** — one per form the user described; `purpose` is one of `contact`, `signup`, `lead`, etc.; `fields` are explicit only.
+- **`gift-cards.enabled`** — `true` when the user explicitly asked for gift cards; `false` (or omit the block) otherwise.
+
+When in doubt, omit a field rather than fabricate. The downstream phases that consume this block aren't built yet — overconfident inference can't be verified until then.
+
+### 2 · Write the slim `.wix/site.json` snapshot
+
+```bash
+mkdir -p .wix
+node "<SKILL_ROOT>/scripts/init-site-json.mjs" \
+    "$(pwd)" "<brand name>" "<one-line aesthetic from Q2>" "<verticals-csv>" \
+    --frontend "<frontend>"
+```
 
-Brief transition messages are fine when major milestones complete (e.g., *"Products seeded, designing pages now"* or the final preview URL), but never surface tool-layer mechanics.
+- `<frontend>` is the value captured in Wave 0 — `astro` on the supported path (the only path that reaches this step; custom frontends are routed to the stub before approval and never write `.wix/site.json`). Always pass it explicitly so the recorded JSON is unambiguous.
+- `<verticals-csv>` is the comma-joined list of all loaded packs (top-level + transitive via `requires:`). For a stores+cms run this is `"stores,ecom,cms,gift-cards"`.
+- `<one-line aesthetic from Q2>` is the short aesthetic tone phrase, not the full 2–3 sentence direction.
+- The script writes a slim `.wix/site.json` containing only `{brand, frontend, verticals}` (plus `siteId` / `appId` once Setup patches them in). It refuses to overwrite an existing file. If a stale site.json is present from a prior run, surface that to the user before retrying — do NOT silently `rm` it.
+- The intent block from § 1 is **not** passed to the script — it lives in orchestrator scratch and feeds seeder prompts directly.
+- **Trust the script's response.** A `{"status": "ok", "path": "..."}` return is the contract — do **not** follow up with a defensive `ls` + `Read` against `.wix/site.json` to confirm. Re-reading costs ~3s and adds nothing.
 
-Proceed to **Setup** (see `SETUP.md`).
+Once `init-site-json.mjs` returns `{"status": "ok"}`, Discovery's domain work is complete. The transition into Setup and the rest of the run is owned by `PLAN.md` (which hands off to `BUILD.md` on approval).

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

@@ -0,0 +1,82 @@
+# Plan — the pre-approval funnel
+
+This file owns the run **from the first Discovery question to the user's approval of the plan** — mode routing, the questions, the background dispatches that hide latency, and the plan/approval gate. Its job is to get the user to the commitment moment **fast**, so keep it lean.
+
+**On approval, open `BUILD.md`** — the post-approval conductor that owns execution (Setup → design-system bridge → Seed → Components → Pages → Build → Release). Everything past the approval gate lives there, so it is not read until the user has committed.
+
+**The contract with the other files.** The domain/step files answer *what each step does* (the questions Discovery asks, the recipes, the prompt templates). This file + `BUILD.md` answer *when, in what order, in parallel with what, gated on what*. The step files do not name the sequence or chain to each other; the conductor (this file → `BUILD.md`) names when to apply each one. Neither prescribes a tool API — map each step to whatever subagent / parallel-execution primitive your runtime offers.
+
+## Concurrency vocabulary
+
+The terms below appear throughout this skill. They describe the *shape* of work; the runtime decides how to implement them:
+
+- **Subagent** — an isolated worker with its own context. The orchestrator sends it a prompt (an `Instruction file` path + inputs); the subagent reads the instruction file, performs the scope, and returns a structured result.
+- **Concurrent batch** — N subagents (or N tool calls) launched together so they execute in parallel rather than serially.
+- **Background subagent** — a subagent the orchestrator does not block on; it runs while the orchestrator continues with downstream work and reports its result asynchronously.
+- **Foreground subagent** — a subagent the orchestrator blocks on before continuing.
+- **Wait (gate)** — the orchestrator pauses until specified background work (subagents or background `Bash` jobs like the scaffold) finishes. **Waiting means awaiting the harness's background-task completion notification — never a `sleep`/poll loop against an output file.** A poll loop burns the whole wait as blocked orchestrator time and delays everything gated behind it (e.g. sleep-polling the scaffold lands the Composer late). The completion notification is the only signal you need; the same rule covers the `wix login` wait (`shared/AUTHENTICATION.md`) and the no-sidecar-poll rule for image phases (`images/INSTRUCTIONS.md`).
+- **Result** — the structured JSON block each subagent returns at the end of its run, per `references/shared/RETURN_CONTRACT.md`.
+
+## Two tracks (business vs frontend)
+
+The run is two semi-independent tracks that the orchestrator interleaves for wall-time:
+
+- **Business track** (frontend-blind) — create/connect the site, **install Wix apps**, **seed backend data**. Inputs: `siteId`, `verticals`, `intent`, `brand`. It never reads `frontend`/template — a product (or collection, post, form) is the same regardless of what renders it. Its domain content lives in `SETUP.md` (app installs) + `SEED.md` (seeders).
+- **Frontend track** (frontend-aware) — scaffold/prep the local project, Designer + design tokens, Composer, components, pages, SDK wiring, build. Every `frontend`/template branch lives here. Its domain content lives in `scaffold.sh` + `seed-utilities.sh` + `DESIGN_SYSTEM.md` / `astro/COMPOSE.md` + the per-vertical references (frontend guides under `references/astro/`).
+
+The only cross-track data flow is **one-way, business → frontend**: seeders produce entity IDs which the orchestrator inlines into the frontend track's Page-subagent prompts. There is no frontend → business dependency.
+
+## Frontend-mode routing
+
+`frontend` (captured by `DISCOVERY.md` § "Wave 0 — Mode detection") is the axis the frontend track branches on. The orchestrator holds it in scratch and uses it in two ways: it branches inline in the PLAN/BUILD orchestration on the scratch value, and it passes `--frontend <value>` to `scaffold.sh` and `init-site-json.mjs` (and `--template astro` to `seed-utilities.sh`). The axis is binary — **astro (supported) vs custom (anything else, not available yet)**:
+
+| `frontend` | Mode | Flow |
+|---|---|---|
+| `astro` | Scaffold (supported) | Wave 0 below → on approval → `BUILD.md`. The full playbook lives under `<SKILL_ROOT>/references/astro/`. |
+| anything else (custom) | Not available yet | Open `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`, surface its not-available message, and **stop** — no scaffold, no Designer/Composer, no Setup/Seed authoring, no `BUILD.md` build flow, no half-built site. |
+
+> **Astro is the one Wix-preferred frontend the skill builds end-to-end.** Every non-astro value (a user-provided project, a Vite/React SPA, anything else) is a **custom** frontend; the custom authoring track is deferred. Route it to the stub and tell the user astro is the supported path. The intended future shape for custom is recorded in `references/custom/INSTRUCTIONS.md`.
+
+This is the **track-selection routing layer**: `SETUP.md`'s steps assume the routing already happened; the conductor owns the branch.
+
+## Wave 0 — Discovery → plan → approval (Path A)
+
+**The funnel dispatches nothing.** Its only job is to talk to the user, present the plan, and get approval. (The scaffold and Designer used to be dispatched here to hide their wall behind Q&A think-time — but the Designer is now ~10–15 s and the scaffold ~23 s, so the hiding isn't worth it, and those dispatches were what distracted the agent from actually showing the plan. **Both now dispatch in `BUILD.md`, post-approval.**) So the funnel is exactly three things:
+
+1. **Mode detection + pre-flight, then the interview** — apply `DISCOVERY.md` (mode detection, CLI auth, Q0 vertical inference, Q1 brand, Q2 vibe, Q2.5 imagery). **Read only what the next question needs** — do not pre-read `BUILD.md`; read the vertical packs for plan composition (not before the vibe question).
+2. **Compose and PRESENT the plan — as a standalone assistant message.** The moment Q&A ends and the aesthetic-direction craft is done, **render the full plan** (Design Direction from the Q2 craft + the Pages/Features tables, per `DISCOVERY.md` § plan) as a normal message the user reads. **The user MUST SEE the rendered plan before being asked to approve.** Do **not** fold the plan into the approval question, do **not** replace it with a one-line "here's the plan" + dispatch, and do **not** do any other work (no scaffold, no Designer, no scaffold-output reads) between the craft and the plan — there is nothing to dispatch here, so present the plan immediately.
+3. **Approval gate** — *only after* the plan message has been sent, ask the approval question (`AskUserQuestion`).
+
+**On approval** — `init-site-json.mjs --frontend <value>` writes the slim `.wix/site.json`, then **open `BUILD.md`** and continue from its run-step 0 (which dispatches the scaffold + Designer, then runs Setup).
+
+## Custom (non-astro) frontends — not available yet
+
+When `frontend` is anything other than `astro`, the run routes to the **custom stub** and stops the frontend track. Open `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`, surface its not-available message, and do **not** attempt authoring — no scaffold, no Designer/Composer, no Setup/Seed, no `BUILD.md`, no half-built site. The user is told astro is the supported frontend.
+
+> **Retired: the Integrate (Path B) flow.** The skill used to run a live "Integrate" sequence for `user-provided` frontends — `DISCOVERY.md` § "Integrate-mode short flow" → `SETUP.md` § "Existing project flow" E1–E6 (E1 init → E2 analyze → E3 install apps → E4 SDK wiring → E5 release). That flow is **no longer dispatched**: non-astro frontends now hit the stub instead. The E1–E6 mechanics (especially the E4 SDK-wiring recipe) are kept in `SETUP.md` as a **historical reference** for the eventual custom authoring track (`references/custom/INSTRUCTIONS.md` § "Intended future shape"), not as a Beta deliverable.
+
+## User-facing output (keep the machinery invisible)
+
+This rule governs the **whole run**, both files. The user should see **milestones in plain language, never the orchestration machinery.** Between the Discovery approval and the final summary the run is largely silent — the orchestrator is dispatching, waiting, and gating, none of which is the user's concern.
+
+**Never put internal orchestration vocabulary in a user-facing message.** That includes: background-handle names (`*_handle`), dispatch markers ("→ dispatch:", "dispatching X", "launching Wave 3"), subagent START/END, "seed gate" / "all handles complete", wave/step numbers ("Wave 3", "Step 4.5"), in-flight **subagent/handle status tables** (especially any "Handle" column), and internal paths (`wix-manage-root`, the scaffold subdir). These describe *how the conductor works*, not *what the user is getting*.
+
+**The only user-facing messages in a Path A run are:**
+1. **Discovery** — the questions, the plan, and the approval gate (`DISCOVERY.md`'s domain).
+2. **One brief seed-progress sentence** (`SEED.md` Step 5) — plain prose naming what was seeded, no tables.
+3. **The final summary** (`BUILD.md` § "Final Message").
+
+Everything else is silent. If a long phase (Components, Pages) would otherwise look stalled, at most **one short plain-language line** ("Building your product and category pages…") — never a status table, handle list, or wave number. The in-flight subagent tables that runs have emitted ("Phase 3 Components running: | Subagent | Handle |…", "🎉 Seed gate open! All handles complete") are the anti-pattern this rule removes.
+
+## Batching discipline
+
+This rule governs **every** concurrent batch in the run — the Wave-0 pack reads (here), and the BUILD-entry scaffold + Designer dispatch, the Setup app-installs, and the Wave-3 seed batch (all in `BUILD.md`). The step files describe *what* is in each batch; the rule that they go out as one batch lives here.
+
+Historical runs lost 1–2 minutes per phase to serialized dispatch — N operations emitted one-per-turn instead of in a single concurrent batch. Even when each ran fast, the inter-dispatch gaps (12–39s in measured runs) accumulated to >25% overhead per phase.
+
+Two mitigations; use both:
+
+1. **Fire the whole batch as one assistant message** — N `Agent`/`Bash` tool_uses as siblings. **No narration between dispatches** ("Now installing apps:", "Dispatching seeders:"). Any text adjacent to a dispatch closes the batch and forces the rest into separate turns, adding seconds per dispatch. This holds even for a 2-item batch (a measured 2-seeder run lost 12 s to one interstitial sentence).
+2. **Use background-on-dispatch for anything that doesn't block downstream work.** Even if the runtime serializes the launch turns, background dispatch lets the work overlap in execution. Measured compression on a sequential-launch / background-execute model: ~2× wall-time vs. serial.
+
+If your runtime forces serialization across turns, make every subagent that can run in the background a background subagent — the Designer, Composer, seeders, and image phases all dispatch background so the foreground never blocks on them.