@wix/agent-skills 1.6.0 → 1.8.0

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

@@ -1,332 +1,76 @@
 # 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, hold the captured contract in orchestrator scratch.
 
-## Step 0 — Infer Vertical(s) and Business Context
+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.
 
-The user's opening message typically names what they want: *"build me a skincare store"*, *"I want to sell handmade jewelry"*, *"create a coffee shop website"*.
+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, which routes on **operation** to `PLAN-create.md` / `PLAN-connect.md`) and `references/BUILD.md` (post-approval, which routes on **framework**).
 
-From the opening message, extract:
-- **Vertical(s)** — which packs to load. See the routing table in `SKILL.md` § "When This Skill Triggers".
-- **Business / product context** — feeds into brand-name suggestions, vibe options, product templates, image prompts.
+**This file is the discovery router, and it routes on OPERATION.** It holds the two things every run does regardless of operation — **Wave 0 field resolution** and the **CLI-auth pre-flight** — then opens the operation-specific discovery file. The actual interview/parse + plan content lives in `DISCOVERY-create.md` (create) or `DISCOVERY-connect.md` (connect). Read only the matching one.
 
-If the opening message is too vague to infer a vertical (e.g., *"build me a site"*, *"I want to go online"*), ask **one conversational clarifier** (NOT an `AskUserQuestion`): *"What do you want your site to do — sell things, publish content, take bookings?"* One sentence. Only ask if you genuinely cannot infer.
+## Wave 0 — Resolve `operation`, then `frontend` (BEFORE any user-facing question)
 
-**Do not ask the user what features they want.** Features are determined by the inferred vertical(s). The user reviews and adjusts the plan at Step 3.
+Discovery routes on **operation** — *create* (the skill writes a new site from a prompt) vs *connect* (the user brings a finished design to wire to Wix). Resolve `operation` **first** from the user's prompt AND the working directory, then derive `frontend` (and `frontendBuild`) *within* that operation. Operation and framework are **orthogonal axes**: `frontendBuild` (`wix`/`none`/`own`) is derived inside the chosen operation, not implied by it — *create + framework-keyword* → `own`, *connect + SPA* → `own`, *connect + static HTML* → `none`, *create + default* → `wix`. Resolving operation first (then framework within it) is the seam that keeps the operation router untouched as frameworks are added (the framework-SPA plan; the extend plan).
 
----
-
-## Step 1 — Brand Name
-
-Use `AskUserQuestion` with a single-select question.
-
-Generate **3–4 brand name suggestions** relevant to the business context, plus a "Type my own" option:
-
-> *"What should we call your brand?"*
-
-Options: [3–4 generated names], Type my own.
-
-Guidelines for generated names:
-- Short (1–3 words), memorable, relevant to the business context
-- Mix styles: one punchy/modern, one descriptive, one abstract/evocative
-- Avoid generic filler (*"Pro Store"*, *"Best Shop"*)
-
-If the user picks *"Type my own"*, follow up conversationally: *"Sure — what should I call it?"*
-
-If the user already named the brand in the opening message, skip this step.
-
-### Background actions on Q1 answer
-
-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.
-
-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.
-
-   **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`)
-
-   Examples: `"Acme-Co" → "acmeco"`; `"Sole Society" → "solesociety"`; `"E&E Co." → "eeco"`; `"AB" → ask the user`.
-
-   The Wix CLI requires `[a-z0-9]{3,20}` — hyphens, underscores, uppercase, and other punctuation are rejected.
-
-   **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
-
-   **The scaffold call (background shell, with timing capture):**
-
-   ```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)
-   ```
-
-   - 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.
-   - 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`
-
-3. **Prefetch loaded pack files** — siblings in the same message:
-   - `Read <SKILL_ROOT>/references/verticals/<pack>.md` for each loaded pack
-
-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.
-
----
-
-## Step 2 — Vibe
-
-Use `AskUserQuestion` with a single-select question. Generate **4 brand personality options** tailored to the inferred business context, plus "Something else":
-
-> *"What's the vibe for [brand name]?"*
-
-Example options for a jewelry store:
-- **Bold & premium** — luxury feel, dark tones, sharp typography
-- **Clean & modern** — minimal, lots of whitespace, crisp lines
-- **Warm & approachable** — friendly, inviting, earthy tones
-- **Something else** — let me describe it
-
-If the user picks "Something else", follow up with `AskUserQuestion` using a text input.
-
-### 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.
-
-Example:
-> *"For Bloom & Root, I'm going with an organic editorial aesthetic — think Kinfolk magazine meets a botanical garden. Warm cream backgrounds, deep forest green accents, Playfair Display for headings paired with Source Sans 3 for body text. Subtle leaf-pattern overlays and generous whitespace to let the products breathe."*
-
-> **Do NOT print this aesthetic direction as a standalone message.** Hold it in session scratch and weave it into the plan (Step 3) as the opening **Design Direction** section. Printing it above the plan detaches the most emotionally important content from the rest. Keep Q2 → plan presentation tight.
-
----
-
-## Step 3 — Present the Plan
-
-Present the plan as formatted markdown. After presenting, use `AskUserQuestion` for approval.
-
-> **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.
-
-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.
-
-### 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.
-
-> **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 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")
-- Color palette (2–3 dominant colors with hex codes)
-- Typography pairing (display + body)
-- Mood and key visual elements
-- Page color strategy: Uniform Light / Uniform Dark / Defined Hybrid
-
-**Section B: Features** — 1–2 line descriptions of user-facing functionality from each pack. Bullet list is correct here. Explain what the user's visitors will be able to do. Tag CMS-powered features with **(CMS-based)** so the user knows which content they can edit from the dashboard.
-
-**Skip features from packs with `disabled: true`** (today: only `gift-cards`). Its surfaces are inactive by default — they light up only when the user enables the matching Wix app from the dashboard. The plan must not promise a feature that isn't active out of the box. The code still ships (the `/gift-cards` page file is created plus the nav/home contributions) so activation is instant once the user opts in — but the plan stays silent until then. Packs without `disabled: true` (including transitive ones like ecom) contribute their features normally.
-
-→ **Verify B:** No bullet derives from a `disabled: true` pack. Today: no "Gift cards" bullet, no "(when enabled)" / "(auto)" markers anywhere in B.
-
-> **Visual separator before the technical scope.** After Section B, emit a `---` rule and a single line: *"Technical scope below — auto-decided from the features above. Skim if you want; not required reading."* This signals to the user that the decision is essentially made and the rest is reference material. Without the cue, users feel obligated to read every table cell before approving and stall the build for tens of minutes.
-
----
-
-**Section C: Pages.** Emit exactly this header, then one row per loaded pack's `routes:` entry:
-
-```
-| Page | Route | Source |
-|------|-------|--------|
-```
-
-> **STOP if you typed anything else.** `| Route | Purpose |` (drops Source), `| Page | Route |` (no Source), bullet list `- **Cart** (/cart)`, or Source merged into Route (`/cart (Stores)`) — each is a known regression. **Three columns, exact names, in that order.** Re-read the skeleton above before typing rows; do not type column headers from memory.
-
-**Compose rows from each loaded pack's `routes:` array.** Do not hardcode rows; do not omit declared rows; do not invent rows. For every loaded pack (top-level OR transitive via `requires:`), iterate its `routes:` array.
-
-**Skip rule.** Skip every route from any pack with `disabled: true`. Today that's only `gift-cards` — its `/gift-cards` row does NOT appear in the plan. The page file still ships so the runtime probe lights up the surface the moment the user enables the Wix Gift Card app from the dashboard, but the plan must not promise a surface the user did not ask for. Surfacing it with a `Source: "Wix Stores (auto)"` marker has been tried and rejected — users push back ("Giftcard shouldn't appear unless the user asked for it").
-
-Each surviving entry → one table row:
-
-```
-Page name (Page cell):
-  - Use the entry's `name:` field if present (override).
-  - Else derive from the route path:
-      "/"               → "Home"
-      "/<seg>/[slug]"   → title-case(seg, singular) + " Detail"
-      otherwise         → title-case the last static segment, replacing
-                          "-" with space  ("/thank-you" → "Thank You")
-
-Route cell:
-  - The entry's `route:` value verbatim (e.g. "/cart" — or the literal
-    string "Hosted by Wix" for Wix-hosted endpoints with no path).
-
-Source cell:
-  - For top-level packs with non-empty `apps:`, use apps[0].name
-    (e.g. "Wix Stores", "Wix Blog").
-  - For transitive packs (loaded via another pack's `requires:`),
-    walk up the requires chain to the top-level puller and use ITS
-    apps[0].name. So ecom's "/cart" shows Source: "Wix Stores"
-    (because stores requires ecom and the user opted into "selling
-    things", not into "an ecommerce SDK").
-  - For the `cms` pack, use the literal "CMS (builtin)".
-  - No suffixes (no "(auto)", no "(passive)", etc.) — disabled packs
-    don't contribute rows at all.
-```
-
-**Order rows by user-facing flow:** CMS pages first (Home, About, FAQ), then catalog/content pages, then transactional pages (cart, thank-you, checkout). Within a pack, preserve declaration order from the pack's `routes:` array.
-
-→ **Verify C:** Header is exactly `| Page | Route | Source |`. Row count = sum of `routes:` entries across all loaded packs that are NOT `disabled: true`. Every Route is either a `/`-prefixed path matching the slugified Page name OR the literal `Hosted by Wix`. No "(auto)"/"(passive)" suffixes anywhere. No "Gift Cards" row when gift-cards loads transitively.
-
----
-
-**Section D: CMS Collections.** Emit exactly this header, then one row per `cmsCollections:` entry from each loaded pack:
-
-```
-| Collection | Key Fields |
-|------------|------------|
-```
-
-> **STOP if you typed `Fields` instead of `Key Fields`.** Re-read the skeleton above.
-
-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:**
+> **Intent is primary; the directory only confirms.** The bug to avoid: an *empty* CWD does **not** automatically mean create. If the prompt brings a design to connect — even one that will be **fetched into the empty dir** — it's connect. Read the prompt first.
 
 ```
-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.
+Read the prompt, then inspect CWD — resolve OPERATION:
+
+1. CONNECT/IMPLEMENT-AN-EXISTING-DESIGN intent in the prompt → operation: connect,
+   EVEN IF THE CWD IS EMPTY. Signals: "connect this to wix", "implement this design",
+   "host/deploy this site", "this is a working site", or a design-file URL to fetch +
+   implement (Claude Design / v0 / Lovable / any tool). The design arrives by fetch into
+   the empty dir — emptiness at check time does not make it create.
+2. CWD already contains a working frontend (`index.html`, `*.html`, `*.jsx`/`*.tsx`/`*.vue`,
+   a design-handoff bundle) → operation: connect — connect the brought-in site.
+3. CWD contains `wix.config.json` → an existing wix-headless project (resume/extend; see
+   SKILL.md § "When NOT to use this skill" — out of pivot scope for now; the extend plan
+   adds `operation: extend` here, ahead of the emptiness tests).
+4. Otherwise — empty CWD AND a CREATE-A-NEW-SITE prompt ("build me a store", "I want to
+   sell tables online", "make a blog") with no design to connect → operation: create.
 ```
 
-→ **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).
-
-### Example (skincare ecommerce brand)
-
-```markdown
-Here's my plan for **Bloom & Root**:
-
-## Design Direction
+Then derive `frontend` and `frontendBuild` **within** the chosen operation, and capture all three in session scratch (the Plan→Build contract core, `PLAN.md` § "The Plan→Build contract"):
 
-For Bloom & Root, I'm going with **clean luxury with organic warmth** —
-think a curated boutique where every product feels considered. Warm cream
-backgrounds paired with deep charcoal text and rose gold accents. Cormorant
-Garamond headlines bring editorial gravity; DM Sans keeps the body text
-tactile and approachable.
+> **Within `create`, branch `frontendBuild` on an explicit framework keyword.** A create prompt that **explicitly names a client-build framework** — `vite`, `react`, `vue`, `svelte`, "SPA", or similar (the same keyword set the connect SPA detector uses) — resolves to **`frontend: custom`, `frontendBuild: own`** (scaffold that framework, then connect via the SPA spine). A create prompt with **no** framework keyword stays **`frontend: astro`, `frontendBuild: wix`** — astro remains the default for a bare *"create a bakery site"*. **Only an explicit keyword flips it** — never infer a framework the user didn't ask for. A framework keyword on a *connect* prompt still routes to connect (the brought-in SPA), per `DISCOVERY-connect.md` § 1.5.
 
-- **Colors:** Warm cream (#FFF8F0), deep charcoal (#1A1A1A), rose gold (#B76E79)
-- **Fonts:** Cormorant Garamond (headings) + DM Sans (body)
-- **Mood:** Premium, approachable, tactile
-- **Color strategy:** Uniform Light
+| `operation` | `frontend` | `frontendBuild` | Wave 0 next |
+|---|---|---|---|
+| `connect` — connect/implement an existing design, OR a working site on disk | `custom` | `none` (static HTML) **or** `own` (framework SPA) — resolved from disk in `DISCOVERY-connect.md` § 1.5 | Pre-flight, then **`DISCOVERY-connect.md`** |
+| `create` — create-a-new-site prompt, **no** framework keyword (the default) | `astro` | `wix` | Pre-flight, then **`DISCOVERY-create.md`** (astro branch) |
+| `create` — create-a-new-site prompt that **explicitly names a client-build framework** (*"…using vite"*) | `custom` | `own` | Pre-flight, then **`DISCOVERY-create.md`** (own branch — minimal scaffold; runs vibe + Designer for brand tokens, but not astro `compose.mjs`) |
 
-## Features
+> **No `AskUserQuestion` for operation/frontend detection.** They are inferred from the prompt + directory, never asked. When intent is unclear, default to `operation: connect` — connecting/implementing what the user brings is the safe interpretation; creating a brand-new site over their intent is the destructive one. **A prompt that fetches or names a design to "connect"/"implement" is `connect` regardless of whether the CWD is empty.**
 
-- **Product catalog** — Browse all products with images, prices, and variants.
-- **Cart & checkout** — Add to cart, review, check out via Wix's hosted checkout.
-- **About (CMS-based)** — Brand story, editable from the Wix dashboard.
-- **FAQ (CMS-based)** — Q&A about products, editable from the dashboard.
+These flow into:
+- The **Plan→Build contract** held in orchestrator scratch (`PLAN.md` § "The Plan→Build contract"). `frontend`, `operation`, and `frontendBuild` all live in scratch — **none** is persisted to disk. The conductor reads `frontendBuild` from scratch to decide whether to run `wix build` before release — `wix` builds, `none` doesn't.
+- **Bootstrap is (operation × framework)-keyed** (`BUILD.md` § "Bootstrap cell"): create+astro runs `scaffold.sh --frontend astro`; create+own runs the framework's own create command (`npm create vite`/…) then `init`; connect (own/none) does **not** scaffold — it bootstraps via `npm create @wix/new@latest init` over the brought-in/scaffolded source.
+- Orchestrator session scratch — every downstream branch reads the scratch values. For `connect`, the frontend track runs the connect flow (`references/custom/INSTRUCTIONS.md`); the create-only project-prep (`seed-utilities.sh`) and the Designer/Composer do not run. (Business-track steps — app install, seeders — never read these fields.)
 
----
+## Pre-flight — Verify CLI auth (BEFORE any user-facing question)
 
-*Technical scope below — auto-decided from the features above. Skim if you want; not required reading.*
+The first Wix touch is the post-approval project bootstrap — create/astro: `scaffold.sh` → `npm create @wix/new@latest headless`; connect: `npm create @wix/new@latest init` — 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 bootstrap runs **after** approval (`BUILD-astro.md` run-step 0 / the connect bootstrap cell, `BUILD.md` § "Bootstrap cell"), a logged-out user wouldn't find out until they'd done discovery *and* approved, only to have it fail immediately. Run the auth check foreground here (both operations) so a logged-out user sees the login prompt first.
 
-## Pages (8)
-
-| Page           | Route             | Source        |
-|----------------|-------------------|---------------|
-| Home           | /                 | CMS (builtin) |
-| About          | /about            | CMS (builtin) |
-| FAQ            | /faq              | CMS (builtin) |
-| Products       | /products         | Wix Stores    |
-| Product Detail | /products/[slug]  | Wix Stores    |
-| Cart           | /cart             | Wix Stores    |
-| 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                                         |
-
-Should I proceed?
+```bash
+npx @wix/cli@latest whoami >/dev/null 2>&1
 ```
 
-The Cart, Thank You, and Checkout rows show `Source: Wix Stores` — not "Wix eCommerce" — because ecom is loaded transitively via stores's `requires:` and the orchestrator walks up the chain. The user opted into "selling things", not into "an ecommerce SDK".
-
-### 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.
-
-### Approval
-
-Use `AskUserQuestion`: *"Ready to build?"* Options: **Yes, build it** / **Adjust something**.
-
-If the user wants to adjust, handle it conversationally (swap brand, change vibe, add/remove a page). Re-present the plan and re-ask for approval.
-
----
+- Exit 0 → open the matching operation discovery file (create → `DISCOVERY-create.md` Step 0; connect → `DISCOVERY-connect.md`).
+- 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 open the matching operation discovery file.
 
-## After Approval
+  Full recovery reference: [`shared/AUTHENTICATION.md`](shared/AUTHENTICATION.md#wix-login-from-a-non-interactive-agent).
 
-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`
+## Next — open the operation-specific discovery
 
-> **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.
+With `operation` (and the derived `frontend`/`frontendBuild`) resolved and auth confirmed:
 
-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.
+- **`create`** → `DISCOVERY-create.md` — the interview (Steps 0–2.5) → plan → approval → hold the contract in scratch.
+- **`connect`** → `DISCOVERY-connect.md` — parse the brought-in site → infer domain → light plan → approval → hold the contract in scratch.
 
-Proceed to **Setup** (see `SETUP.md`).
+Read only the matching file. The pre-approval funnel (`PLAN-create.md` / `PLAN-connect.md`) names *when* to apply each discovery step.

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

@@ -0,0 +1,19 @@
+# Plan — connect operation (custom)
+
+The pre-approval funnel when `operation === "connect"` (the user brought a finished site to connect; `frontend: custom`, `frontendBuild: none` for static HTML or `own` for a framework SPA — resolved in `DISCOVERY-connect.md` § 1.5). Shared funnel rules — concurrency vocabulary, the two-track model, the Plan→Build contract, user-facing output, batching discipline — live in `PLAN.md`; this file is the connect funnel only. Domain (parse + infer + plan content) is owned by `DISCOVERY-connect.md`. **The funnel is framework-blind** — it parses, presents a light plan, and approves identically whether the brought-in frontend is static HTML or an SPA; only the downstream Build mechanics differ (Build routes on `frontendBuild`).
+
+**Input = the brought-in site**, processed by parse + infer (`DISCOVERY-connect.md` §§ 1–2). **Plan shape = a light plan** (detected-site summary + what to wire/add/persist + apps, `DISCOVERY-connect.md` § 3) — not the astro Design-Direction card. The plan also resolves the **connection plan** that fills the contract's operation section (binding-map / augmentation / persistence-swap), consumed downstream only at the wiring cell.
+
+## Wave 0 — Connect discovery → plan → approval (Path B)
+
+**The funnel dispatches nothing.** Its only job is to parse the site, present the plan, and get approval. Same three-step shape as the create funnel, planning content aside:
+
+1. **Parse + infer** — apply `DISCOVERY-connect.md` §§ 1–2: read the brought-in site (markup, copy, tokens; opportunistically a Claude-Design bundle), infer the domain → Wix capability (the universal floor is a Wix Forms contact/lead form), and infer the brand.
+2. **Compose and PRESENT the light plan — as a standalone assistant message.** Render the connect plan (`DISCOVERY-connect.md` § 3): *what I found* (site type + detected regions) and *what I'll connect* (regions to **wire** + the component to **add** + apps to install). The user sees the plan before being asked to approve — do not fold the plan into the approval question.
+3. **Approval gate** — *only after* the plan message has been sent, ask the approval question (`AskUserQuestion`).
+
+**On approval** — hold the contract in scratch (`frontend: custom` + inferred capabilities + brand + `frontendBuild`), then **open `BUILD.md`** — it routes Build on `frontendBuild` to `BUILD-own-build.md`:
+- **`none` (static HTML):** bootstrap cell (`init` + connection plan) → shared Setup (app installs only; **no `env pull`, no per-pack `npm install`**) → shared Seed → wiring cell (inject `<script>`) → **inline no-build release** (`npx @wix/cli@latest release` — no `wix build`).
+- **`own` (framework SPA):** bootstrap cell (`init` over the SPA + connection plan reading source) → shared Setup + **bundled `npm install @wix/sdk`** → shared Seed (incl. the CMS collection a persistence swap targets) → wiring cell (rewrite the source data layer → `@wix/data`) → **the project's own `npm run build`** → release. Never `wix build`.
+
+> **Always connect.** The connect operation must end with the site reading from or writing to Wix; `init`+`release` of a static page with no connection is not acceptable (`references/custom/INSTRUCTIONS.md` § "Two locked principles"). The per-capability `custom/<cap>/WIRING.md` guides own the wiring step.

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

@@ -0,0 +1,17 @@
+# Plan — create operation
+
+The pre-approval funnel when `operation === "create"` (the skill writes the site). Shared funnel rules — concurrency vocabulary, the two-track model, the Plan→Build contract, user-facing output, batching discipline — live in `PLAN.md`; this file is the create funnel only. Domain (the questions, the plan content) is owned by `DISCOVERY-create.md`. The funnel **dispatches nothing** in either framework branch; it differs only in plan shape and where it hands off (Build routes on `frontendBuild`):
+- **`frontendBuild: wix` (astro — default):** the full interview + decision card below.
+- **`frontendBuild: own` (framework SPA — named-framework create):** the **light** plan from `DISCOVERY-create.md` § "Framework-SPA branch" (no astro decision card, but it **does** run the vibe question + the Designer — the brand tokens are framework-agnostic and the SPA imports them); on approval, hold the contract in scratch (`frontend: custom`, `frontendBuild: own`), then `BUILD.md` routes `own` → `BUILD-own-build.md` (create × own cells). The astro funnel below does not apply.
+
+**Input = the user's prompt** (astro branch), processed by the interview (`DISCOVERY-create.md` Steps 0–2.5). **Plan shape = the full decision card** (Design Direction + Features + Pages, `DISCOVERY-create.md` § "Step 3").
+
+## Wave 0 — Discovery → plan → approval (Path A)
+
+**The funnel dispatches nothing — scaffold + Designer dispatch post-approval in `BUILD-astro.md`.** Its only job is to talk to the user, present the plan, and get approval. So the funnel is exactly three things:
+
+1. **The interview** — Wave-0 field resolution (operation/frontend/frontendBuild) + CLI auth already ran in `DISCOVERY.md` (shared). Now apply `DISCOVERY-create.md` (Q0 vertical inference, Q1 brand, Q2 vibe, Q2.5 imagery). **Read only what the next question needs** — do not pre-read `BUILD-astro.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-create.md` § "Step 3") 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** — hold the contract in scratch (`frontend: astro`, `frontendBuild: wix`), then **open `BUILD.md`** — it routes Build on `frontendBuild` (`wix` here) to `BUILD-astro.md`; continue from its run-step 0 (which dispatches the scaffold + Designer, then runs Setup).

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

@@ -0,0 +1,92 @@
+# Plan — the pre-approval funnel
+
+This file owns the run **from the first Discovery question to the user's approval of the plan** — operation 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.
+
+**This file is the funnel router, and it routes on OPERATION.** It holds the shared funnel rules (concurrency vocabulary, the two-track model, operation routing, the Plan→Build contract, user-facing output, batching). The operation-specific funnel — how input is processed and how the plan looks — lives in `PLAN-create.md` (create a new site) and `PLAN-connect.md` (connect a brought-in design). **Read `operation` (set by `DISCOVERY.md` § Wave 0), then open the matching one and read only that:** `create` → `PLAN-create.md`, `connect` → `PLAN-connect.md`. (Today `create` coincides with `frontend: astro` and `connect` with `frontend: custom` — but the funnel branches on the *operation*, not the frontend; that is the seam the framework-SPA and extend plans build on.)
+
+**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 + the operation funnels + `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 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, `compose.mjs` (the Composer script), components, pages, SDK wiring, build. Every `frontend`/template branch lives here. Its domain content lives in `scaffold.sh` + `seed-utilities.sh` + `DESIGN_SYSTEM.md` + `scripts/compose.mjs` (self-documenting) + 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.
+
+## Operation routing
+
+The Plan phase routes on **operation** — *create* (scaffold a new site from a prompt) vs *connect* (integrate a brought-in design). `operation` is captured by `DISCOVERY.md` § "Wave 0", held by the orchestrator in scratch, and selects the funnel:
+
+| `operation` | What it is | Funnel → Build |
+|---|---|---|
+| `create` | The user asks for a new site; the skill writes it | **`PLAN-create.md`** → on approval → `BUILD.md` routes Build on **framework**. The full astro playbook lives under `<SKILL_ROOT>/references/astro/`. |
+| `connect` | The user brings a finished design to wire to Wix | **`PLAN-connect.md`** → on approval → `BUILD.md` routes Build on **framework**. The frontend-track playbook is `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`. No scaffold, no Designer/Composer; init + shared Setup/Seed + connect/augment/persistence-swap; release is no-build (`none`) or the project's own build (`own` SPA). |
+
+> **Operation ≠ frontend.** The funnel branches on the *operation* (what the user is doing), not the frontend (what renders it). The two are orthogonal: *create* spans `frontendBuild` `wix` (astro default) and `own` (a named framework); *connect* spans `none` (static HTML), `own` (a brought SPA), and could span `wix` (a brought astro project) — none of which forks the operation router. Keeping operation and framework distinct is what lets these combinations be independently expressible without a new phase fork — see the framework-SPA plan and the extend plan.
+
+This is the **operation-selection routing layer**: `SETUP.md`'s steps assume the routing already happened; the conductor owns the branch. **Build does NOT route on operation** — it routes on framework (`BUILD.md`); operation feeds Build only through the contract below (specifically the bootstrap/wiring cells).
+
+## The Plan→Build contract
+
+Plan resolves a small, explicit contract that Build consumes. It is carried **in the orchestrator's in-context session scratch** and threaded into each subagent's dispatch prompt — it is **not persisted to disk** (nothing in this contract lands on disk). The orchestrator already resolves these fields in Wave 0 and holds them for the whole run, so a disk round-trip buys nothing; on scratch loss, `frontend`/`frontendBuild` are recovered from `package.json` (`@wix/astro` ⇒ astro/wix, else custom + re-derive from `scripts.build`).
+
+**Core (every operation resolves these identically; Build's install/build/release spine reads only these):**
+
+| Field | Today's values | Meaning |
+|---|---|---|
+| `operation` | `create` \| `connect` | what the user is doing (*extend* added later by its own plan) |
+| `frontend` | `astro` \| `custom` | what renders the site (held in scratch; recovered from `package.json` on scratch loss) |
+| `frontendBuild` | `wix` \| `none` \| `own` | the build-class Build routes on: `wix` (astro, `wix build`), `none` (brought static HTML, no build), `own` (framework SPA — the project's own `npm run build`; brought-in *or* scaffolded from a named framework) |
+| `verticals[]` | e.g. `["stores","ecom","cms"]` | loaded packs (top-level + transitive) |
+| `designSource` | `generate-fresh` \| `derive-from-brought` | create generates; connect derives from the brought design's own tokens |
+| `brand` | `{ name, description }` | brand metadata |
+
+`frontendBuild` is **derived inside the operation, not implied by it** (the axes are orthogonal): connect resolves it from the brought-in project on disk (`none` static HTML vs `own` framework SPA — `DISCOVERY-connect.md` § 1.5); create resolves it from an explicit framework keyword (`wix` astro default vs `own` named framework — `DISCOVERY.md` § "Wave 0"). Resolve it in Wave 0 alongside `frontend` and hold it in scratch (on scratch loss, recover from `package.json`). Build branches its install/build/release **purely off `frontendBuild`** — never off `operation`.
+
+**Operation section (feeds ONLY the bootstrap + wiring cells, never the build/release spine):**
+- `connect` carries the **connection plan** (binding-map / augmentation spec) inferred in Discovery.
+- `create` carries nothing extra.
+- *(extend will carry existing-state + delta — added by the extend plan.)*
+
+That is the precise sense in which the contract stays uniform across operations: the build/release spine is contract-uniform (it reads only the core), and **only** the bootstrap/wiring cells read the operation-specific payload. A *fresh session over an existing project* (extend) reconstructs the equivalent core from durable disk artifacts (`@wix/astro` dep, `package.json`, on-disk pages) rather than from scratch — same contract, sourced differently by lifecycle.
+
+## User-facing output (keep the machinery invisible)
+
+This rule governs the **whole run**, both modes. 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 run are:**
+1. **Discovery** — the questions, the plan, and the approval gate (the mode discovery file'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, in both modes — the Wave-0 pack reads (mode funnel), and the post-approval dispatch batches owned by the conductor (`BUILD.md` and its mode files): the astro BUILD-entry scaffold + Designer dispatch, the Setup app-installs, the Wave-3 seed batch, the integration connection-plan + init batch. 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 accumulated to significant 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.
+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, compressing wall-time substantially versus serial.
+
+If your runtime forces serialization across turns, make every subagent that can run in the background a background subagent — the Designer, seeders, and image phases all dispatch background so the foreground never blocks on them. (The Composer is no longer a subagent — it is the deterministic `compose.mjs` Bash step, sub-second and synchronous.)