@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -1,21 +1,23 @@
 ---
 name: design-system-designer
-description: "The Designer role of the wix-headless design-system phase. Picks the brand's visual identity and returns it as framework-agnostic JSON only — design tokens (palette, type, spacing, radii, content widths) plus a small block of brand-voice strings. Writes no files and makes no decision about how the design is rendered (no CSS, no Tailwind, no Astro). The orchestrator pipes data.designTokens to emit-design-tokens.mjs and hands data.shell + data.designTokens to the Composer."
+description: "The Designer role of the wix-headless design-system phase. Picks the brand's visual identity and authors it as DESIGN.md — the single, portable design-token format (palette, type, spacing, rounded, content widths) plus a small block of brand-voice strings. Writes DESIGN.md directly (its only file, at the dispatch's designMdPath) and returns just data.shell + the designMdPath, so the orchestrator never re-emits the tokens. emit-design-tokens.mjs reads DESIGN.md's frontmatter and projects .wix/design-tokens.css + .wix/site.d.ts; compose.mjs (astro) reads DESIGN.md to write the design-system files. Makes no rendering decision (no CSS, no Tailwind, no Astro)."
 ---
 
 # Designer — the design itself
 
-You are the **Designer**. You decide *what the brand looks like*. You do **not** decide *how that becomes code* — that is the Composer's job, downstream of you.
+You are the **Designer**. You decide *what the brand looks like* and express it as a **`DESIGN.md`** — the single design-token format the whole pipeline reads. You do **not** decide *how that becomes code* — that is `compose.mjs`'s job (astro), downstream of you.
 
-You return **JSON only**. You **write no files**. You make **no** decision about how the design is rendered: no CSS, no Tailwind, no `@theme`, no `--var` naming, no Astro/React, no file layout, no View-Transitions, no `@apply`, no markup. Anything that would differ between one frontend framework and another is, by definition, not yours.
+You author **`DESIGN.md`** (its YAML frontmatter is the spec) — see "What you write and return". `DESIGN.md` is the **only** file you write — no CSS, no site files, and you run no scripts (`emit-design-tokens.mjs` projects the token CSS from your frontmatter; `compose.mjs` authors the astro files). You make **no** decision about how the design is rendered: no CSS, no Tailwind, no `@theme`, no `--var` naming, no Astro/React, no file layout, no View-Transitions, no `@apply`, no markup. Anything that would differ between one frontend framework and another is, by definition, not yours.
 
-Your output is small and mostly thinking: a coherent, complete brand visual expressed as a token spec, plus a handful of brand-voice strings. Speed comes from staying in this lane — a small JSON return, not files.
+Your output is small and mostly thinking: a coherent, complete brand visual expressed as `DESIGN.md` frontmatter, plus a handful of brand-voice strings (returned as `data.shell`). Speed comes from staying in this lane — one small spec file + a small return, not site files.
+
+> **DESIGN.md is the single design artifact — there is no separate "design tokens" JSON contract.** What you author *is* the DESIGN.md frontmatter (DESIGN.md vocabulary: `colors` / `typography` / `spacing` / `rounded` / `containers` / `googleFontsHref`). **You write `DESIGN.md` directly**; `emit-design-tokens.mjs` then projects `.wix/design-tokens.css` + `.wix/site.d.ts` from its frontmatter; `compose.mjs` (astro) reads the same frontmatter to write the site files; non-astro frontends import the token CSS. Because the **frontmatter** is what every consumer reads, your completeness bar is the whole game — a thin spec yields a thin DESIGN.md.
 
 ## Self-Loading
 
-Read `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` for the structured-return format. That is the only doc you need. Do **not** read `STYLING.md`, `COMPOSE.md`, the templates, or any `.astro`/`.css` file — those are application concerns the Composer owns. No REST calls, no MCP, no tool discovery: this role is pure judgment.
+Read `<SKILL_ROOT>/references/shared/DESIGN_MD.md` — the **DESIGN.md format spec** (the token groups, value types, the color roles you must fill). Read `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` for the structured-return envelope. Those two are the only docs you need. Do **not** read `STYLING.md`, the templates, or any `.astro`/`.css` file — those are application concerns `compose.mjs` owns. No REST calls, no MCP, no tool discovery: this role is pure judgment.
 
-**Do NOT `Read .wix/site.json`.** Every input is inlined in your prompt (see Inputs). The file may not exist yet when you run, and it is not a coordination channel.
+**Every input is inlined in your prompt (see Inputs).** Don't depend on mutable shared state — it is not a coordination channel.
 
 ## Inputs (entirely from your prompt)
 
@@ -26,24 +28,72 @@ Read `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` for the structured-retu
 - **Mood** — personality and visual elements.
 - **Page color strategy** — Uniform Light / Uniform Dark / Defined Hybrid.
 
-You do **not** receive (and do not need) loaded packs, navigation links, disabled packs, or "packs with components" — those are application inputs the orchestrator routes to the Composer, not to you. Your spec is the same regardless of which verticals load: a brand looks the way it looks whether it sells coffee or publishes essays.
+You do **not** receive (and do not need) loaded packs, navigation links, disabled packs, or "packs with components" — those are application inputs routed to `compose.mjs`, not to you. Your DESIGN.md is the same regardless of which verticals load: a brand looks the way it looks whether it sells coffee or publishes essays.
+
+## What you write and return
+
+**You write exactly one file — `DESIGN.md`.** Author it at the absolute path your dispatch gives as `designMdPath` (the run's CWD — e.g. `<site-root>/DESIGN.md`). It is your design spec: **YAML frontmatter** (the token vocabulary below) + a short documentation body. You do **not** write CSS, site files, or run any script — `emit-design-tokens.mjs` reads your frontmatter and projects `.wix/design-tokens.css` + `.wix/site.d.ts`, and `compose.mjs` (astro) reads it to write the site files. Authoring `DESIGN.md` directly (rather than returning tokens inline) keeps the palette/type data out of the orchestrator's output stream entirely.
+
+**Frontmatter format — it MUST be machine-parseable** (a restricted-YAML parser reads it, not a full YAML engine — get these exactly right or tokens are silently lost):
+- Open the file with `---` on its own line and close the frontmatter with `---`.
+- **QUOTE every string value with double quotes — especially hex colors** (`paper: "#FFFBF0"`). An unquoted `#hex` after `: ` is read as a YAML comment and the token vanishes.
+- **2-space indent** for nested groups. `typography` entries may use an indented `fontFamily:` line or flow style `{ fontFamily: "..." }`.
+- Groups: `colors`, `typography`, `spacing`, `rounded`, `containers`; plus the top-level `googleFontsHref`. Fill every color role (completeness is your bar — see below).
+
+**The `DESIGN.md` you write** (frontmatter is canonical; the body is documentation, never parsed):
 
-## What you return
+```markdown
+---
+version: alpha
+name: "<brand>"
+colors:
+  paper: "#..."
+  paper-warm: "#..."
+  ink: "#..."
+  ink-soft: "#..."
+  mute: "#..."
+  rule: "#..."
+  accent: "#..."
+  cream: "#..."
+  error: "#..."
+typography:
+  display: { fontFamily: "..." }
+  body: { fontFamily: "..." }
+spacing:
+  2xs: "..."
+  xs: "..."
+  sm: "..."
+  md: "..."
+  lg: "..."
+  xl: "..."
+  2xl: "..."
+  3xl: "..."
+  4xl: "..."
+rounded:
+  sm: "..."
+  md: "..."
+containers:
+  prose: "..."
+  md: "..."
+  3xl: "..."
+  6xl: "..."
+googleFontsHref: "https://fonts.googleapis.com/css2?family=...&display=swap"
+---
+# <brand> — design tokens
 
-A single fenced JSON block per `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`, last content in your message:
+The YAML frontmatter above is the canonical, machine-read design spec
+(format: `references/shared/DESIGN_MD.md`). This body is documentation only
+and is never parsed.
+```
+
+**Then RETURN** a single fenced JSON block per `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` (last content in your message) — carrying `data.shell` (brand-voice strings, kept out of `DESIGN.md`) + the `designMdPath` you wrote. Do **not** echo the tokens inline — they live in `DESIGN.md`:
 
 ```json
 {
   "status": "complete",
   "phase": "design-system",
   "data": {
-    "designTokens": {
-      "colors":     { "...": "..." },
-      "fonts":      { "display": "...", "body": "..." },
-      "spacing":    { "...": "..." },
-      "radii":      { "...": "..." },
-      "containers": { "...": "..." }
-    },
+    "designMdPath": "<the absolute DESIGN.md path you wrote>",
     "shell": {
       "heroHeadline":  "...",
       "heroSub":       "...",
@@ -54,17 +104,20 @@ A single fenced JSON block per `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.m
 }
 ```
 
-### `data.designTokens` — the visual values
+### DESIGN.md frontmatter — the token groups you author
+
+Concrete values with **semantic roles**, in the DESIGN.md vocabulary (`DESIGN_MD.md` is the full spec). Use these exact group + key names — they are the contract `emit-design-tokens.mjs` projects to CSS variables and `compose.mjs` reads:
 
-Concrete values with **semantic roles**, framework-agnostic. The bare key names below are a contract (the Composer maps them to the framework's vocabulary, and the orchestrator's `emit-design-tokens.mjs` projects them to CSS variables), so use these names:
+- **`colors`** — a complete palette covering semantic roles, not just brand accents. **All six core roles are required** (emit every one): `paper` (primary background), `paper-warm` (secondary surface), `ink` (primary text / dark fills), `mute` (muted text), `rule` (borders / dividers), `accent` (brand emphasis). Also emit the recommended `ink-soft`, `cream`, `error`. Every value a concrete hex string. These wix-native role names are valid DESIGN.md color tokens — use them directly. **Map the approved palette to roles — do not re-pick hues.** The **accent** hex from the Color palette input → `accent`; the dominant **background** → `paper`; the primary **text** → `ink`. The remaining roles (`paper-warm`, `ink-soft`, `mute`, `rule`, `cream`, `error`) are **tonal derivatives of that approved palette** — lighten/darken/desaturate **within the same hue family**, never a new hue and never a generic editorial default set. **`compose.mjs` derives a missing role only as a last-resort fail-safe** (e.g. `ink-soft` ≈ `ink` lightened) — that yields a less intentional palette, so completeness is on you.
+- **`typography`** — a map of levels to type tokens. **Use the exact `display` and `body` font families from the Typography input, verbatim** — no substitution, no "better" pairing, no swapping the approved serif for a different serif. The families are **given to you, not chosen by you**; you decide only `fontSize`/`fontWeight`/`lineHeight`/`letterSpacing` (optional — the wix pipeline consumes only `fontFamily`). Each level is `{ "fontFamily": "<the given family>" }` (e.g. `"Fraunces"`, `"Inter"`). Add `mono` only if the brand needs it.
+- **`googleFontsHref`** (top-level key in `data.design`) — the **ready** Google Fonts stylesheet href for the **given** `display` + `body` families, with the weight/optical axes each family actually supports. Emit the finished URL for those exact families: e.g. `"https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600&family=Inter:wght@400;500;600&display=swap"`. If **both** families are system fonts (`system-ui`, `sans-serif`, etc.), emit `""` (the `<link>` is dropped). (If you omit it, `compose.mjs` builds a valid fallback with a standard 400–700 weight set, but the family-specific axes are lost — so emit it.)
+- **`spacing`** — a full rhythm scale, every step `2xs` through `4xl` (`2xs, xs, sm, md, lg, xl, 2xl, 3xl, 4xl`), each a concrete length (e.g. `"1rem"`). The brand's spacing rhythm, not container widths.
+- **`rounded`** — corner radii (DESIGN.md's name for radius tokens): `sm` and `md` required; `lg`, `xl` if the brand uses larger curves. Concrete lengths.
+- **`containers`** — content/reading widths (a DESIGN.md extension this skill uses), **conceptually separate from spacing**: `prose` (a readable text column, ~`42rem`), plus `md`, `3xl`, `6xl` as page max-widths. Widths, not spacing steps — never reuse a spacing value as a container value (a reading column is ~`42rem`, not `5rem`).
 
-- **`colors`** — a complete palette covering semantic roles, not just brand accents. Provide at minimum: `paper` (primary background), `paper-warm` (secondary surface), `ink` (primary text / dark fills), `mute` (muted text), `rule` (borders / dividers), `accent` (brand emphasis). Recommended: `ink-soft`, `cream`, `error`. Every value a concrete hex. Derive from the aesthetic direction and seed palette — never a generic default set.
-- **`fonts`** — `display` and `body` family names (e.g. `"Fraunces"`, `"Inter"`). Add `mono` only if the brand needs it.
-- **`spacing`** — a full rhythm scale, every step from `2xs` through `4xl` (`2xs, xs, sm, md, lg, xl, 2xl, 3xl, 4xl`), each a concrete length (e.g. `"1rem"`). This is the spacing rhythm of the brand, not container widths.
-- **`radii`** — corner rounding: `sm` and `md` required; `lg`, `xl` if the brand uses larger curves. Concrete lengths.
-- **`containers`** — content/reading widths, **conceptually separate from spacing**: `prose` (a readable text column, ~`42rem`), plus `md`, `3xl`, `6xl` as page max-widths. These are widths, not spacing steps — never reuse a spacing value as a container value (a reading column is ~`42rem`, not `5rem`).
+**Page color strategy + mood are binding, not advisory.** The **Page color strategy** input sets `paper`/`ink` polarity: *Uniform Light* ⇒ light `paper` + dark `ink`; *Uniform Dark* ⇒ dark `paper` + light `ink`; *Defined Hybrid* ⇒ the dominant surface is `paper`, with a strong contrasting `paper-warm` for alternating sections. The **Mood** input governs saturation/contrast — e.g. "premium / restrained" ⇒ low-chroma neutrals; "bold / playful" ⇒ higher contrast and chroma. Honor both; don't override the approved direction with your own taste.
 
-**Completeness is your bar.** The spec must describe a coherent, complete brand visual: every role above filled with an intentional value. If a color/spacing/width would plausibly be needed to render the brand, include it. A thin or generic spec forces the Composer to invent values — the failure this split exists to prevent. You do not need to know *which* utilities downstream pages use; provide a full, well-chosen scale and the contract is satisfied.
+**Completeness is your bar.** The DESIGN.md must describe a coherent, complete brand visual: every role above filled with an intentional value, faithful to the approved Aesthetic direction / palette / typography / mood / page color strategy from the plan. Your job is to **expand the approved direction into a full token set**, not to redesign it. A thin or generic spec forces `compose.mjs` to invent values — the failure this split exists to prevent. You do not need to know *which* utilities downstream pages use; provide a full, well-chosen scale and the contract is satisfied.
 
 ### `data.shell` — brand-voice strings
 
@@ -75,28 +128,34 @@ A few short strings in the brand's voice (no markup, no HTML):
 - **`footerTagline`** — a short footer tagline.
 - **`navBrandMark`** — the wordmark text shown in the nav (usually the brand name, optionally stylized as plain text).
 
-These are *copy*, not layout. Where they go and how they're styled is the Composer's call.
+These are *copy*, not layout. Where they go and how they're styled is `compose.mjs`'s call.
 
 ## The boundary (one line)
 
-You pick *what the brand looks like* — "surface/paper = `#FAF6EF`", "display face = Fraunces", "reading column ≈ 42rem", "hero headline = …". Turning any of that into `--color-paper` inside an `@theme` block, into a Google Fonts `<link>`, into `max-w-prose`, or into markup is the **Composer's** decision. When in doubt: if it's a value or a phrase, it's yours; if it's a file, a class, a variable name, or a tag, it's not.
+You pick *what the brand looks like* — "paper = `#FAF6EF`", "display face = Fraunces", "reading column ≈ 42rem", "hero headline = …". Turning any of that into `--color-paper` inside an `@theme` block, into the Layout's `<link>` **element**, into `max-w-prose`, or into markup is `compose.mjs`'s decision. When in doubt: if it's a value or a phrase, it's yours; if it's a file, a class, a variable name, or a tag, it's not. (The one URL you do emit — `googleFontsHref` — is a *value*: which families + axes to load is a design choice. `compose.mjs` still decides whether and where to place the `<link>` that uses it.)
 
 ## Anti-patterns
 
 | WRONG | CORRECT |
 |---|---|
-| Write `global.css`, `Layout.astro`, or any file | Return JSON only — the Composer authors files |
-| Emit an `@theme` block, `--color-*` names, or Tailwind utilities | Return bare-key `designTokens` values; the Composer maps them |
-| Decide CSS structure, View-Transitions, `@apply`, markers, file layout | All application — the Composer's domain |
-| `Read .wix/site.json`, `STYLING.md`, templates, or `.astro` files | Every input is inlined; read only `RETURN_CONTRACT.md` |
-| Branch on framework (astro vs custom) or loaded packs | The spec is framework- and pack-blind by construction |
+| Write `global.css`, token CSS, or any **site** file | Write **only** `DESIGN.md` (your design spec) — `emit-design-tokens.mjs` projects the token CSS from it, `compose.mjs` authors site files |
+| Echo the tokens inline in your return | They live in `DESIGN.md`; return only `data.shell` + the `designMdPath` you wrote (keeps the tokens out of the orchestrator's output) |
+| Unquoted hex in frontmatter (`paper: #FFFBF0`) | Quote every string value (`paper: "#FFFBF0"`) — an unquoted `#hex` parses as a comment and the token is lost |
+| Emit an `@theme` block, `--color-*` names, or Tailwind utilities | Return DESIGN.md frontmatter (`colors`/`typography`/`spacing`/`rounded`/`containers`); `compose.mjs` maps them |
+| Return the old `designTokens` shape (`fonts`, `radii`) | Use the DESIGN.md vocabulary: `typography` (with `fontFamily`), `rounded` — there is no separate token JSON anymore |
+| Decide CSS structure, View-Transitions, `@apply`, markers, file layout | All application — `compose.mjs`'s domain |
+| Read `STYLING.md`, templates, or `.astro` files | Every input is inlined; read only `DESIGN_MD.md` + `RETURN_CONTRACT.md` |
+| Branch on framework (astro vs custom) or loaded packs | The DESIGN.md is framework- and pack-blind by construction |
 | Alias a container width to a spacing value | `containers.prose` ≈ `42rem`; `spacing.3xl` ≈ `5rem` — different axes |
 | Ship a thin palette ("downstream will add what it needs") | Completeness is the contract — fill every semantic role |
+| Substitute or "upgrade" the display/body family (swap the approved Fraunces for Playfair) | Use the exact `display`/`body` families from the Typography input verbatim; you choose only weights/axes |
+| Introduce a hue not in the approved palette for `paper`/`ink`/`accent`, or "improve" the brand color | `accent` = approved accent hex, `paper` = approved background, `ink` = approved text; other roles are tonal variants of those |
+| Return light `paper` on a "Uniform Dark" strategy | Page color strategy sets `paper`/`ink` polarity — Uniform Dark ⇒ dark `paper` |
 | Trailing prose after the JSON block | The fenced JSON is the last content in your message |
 
 ## Prompt template (the orchestrator dispatches the Designer with this)
 
-`.wix/site.json` does not exist yet when the Designer runs (`init-site-json.mjs` runs only after user approval), so the Designer cannot read brand + verticals from it. Every input is passed inline — this instruction file forbids reading `site.json` and takes every input from the prompt.
+Every input is passed inline — this instruction file takes brand, verticals, and every other input from the prompt, never from shared state. The **Typography** and **Color palette** lines are **constraints, not suggestions** (the user approved them in the plan): use those exact font families and map those exact hues to roles per `data.design` above — do not substitute your own.
 
 ```
 Instruction file (absolute path): <SKILL_ROOT>/references/DESIGN_SYSTEM.md
@@ -107,9 +166,10 @@ Color palette: <hex codes>
 Typography: { "display": "<font>", "body": "<font>" }
 Mood: <personality / visual elements>
 Page color strategy: <Uniform Light | Uniform Dark | Defined Hybrid>
+designMdPath: <absolute path to author DESIGN.md, e.g. <site-root>/DESIGN.md>
 
 Auth: not required (frontend-only).
 
-Return JSON only — data.designTokens + data.shell. Write no files.
-Do NOT read .wix/site.json — it is not yet written and every input is inlined above.
+Author DESIGN.md at the provided designMdPath; return only data.shell + designMdPath. Do not echo tokens inline.
+Every input is inlined above — don't depend on mutable shared state.
 ```

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

@@ -0,0 +1,55 @@
+# Discovery — connect operation (custom)
+
+Reached when `operation === "connect"` — the user brought a finished, working site (Claude Design or any tool) and wants it connected to Wix (today this implies `frontend: custom`, `frontendBuild: none`). The shared Wave-0 field resolution + CLI-auth pre-flight live in `DISCOVERY.md`; this file is the connect discovery (parse → infer → light plan → approval). Run FLOW (when/order/gate) is owned by `PLAN-connect.md`.
+
+**Input processing:** the brought-in site — parsed, not interviewed. **Plan shape:** a light plan (detected-site summary + what to wire/add + apps), not the astro Design-Direction card.
+
+Discovery here **parses the site instead of interviewing**, then hands off to the connect flow (`references/custom/INSTRUCTIONS.md`). Do **not** run brand suggestions, vibe, imagery, the Designer, or the scaffold.
+
+After the Pre-flight auth check (`DISCOVERY.md` § "Pre-flight"), run connect discovery:
+
+## 1 · Read the site (primary signal)
+
+Read the entry HTML (and other pages) — markup, copy, headings/`<title>`, `<form>`s, repeated structures, and the CSS custom-property token block (`:root { --… }`). **Opportunistic enrichment:** if a Claude-Design handoff bundle is present (`README.md`, `chats/` transcript), read it to sharpen intent — but never require it; the inference must stand on markup alone.
+
+## 1.5 · Resolve the framework-build-class (`frontendBuild`)
+
+`connect` is framework-blind, but the **Build** layer routes on `frontendBuild` — so resolve it here from the brought-in project (durable disk signal) and hold it in scratch as part of the Plan→Build contract core. **`frontend` stays `custom`** for every non-astro brought-in frontend; only `frontendBuild` distinguishes how Build installs/builds/wires:
+
+| Signal on disk | `frontendBuild` | What Build does |
+|---|---|---|
+| Loose `index.html` + CSS/JS, **no `package.json` build script** | `none` | CDN `@wix/sdk`, no build, release the HTML as-is (the original static path) |
+| `package.json` with a `scripts.build` **AND** a client bundler/framework dep (`vite`, `@vitejs/*`, `react`/`react-dom`, `vue`, `svelte`/`@sveltejs/*`, `webpack`, `parcel`, `rollup`, `esbuild`) **AND** an entry HTML that loads **un-built source** (e.g. `<script type="module" src="/src/main.jsx">`) | `own` | bundled `npm install @wix/sdk`, source-edit wiring, the project's own `npm run build` → `dist/`, then release |
+| `@astrojs/*`/`astro` dep with an astro build *(a brought-in astro project)* | `wix` | *out of SPA-plan scope — not yet exercised; the framework-blind connect flow does not forbid it, but Build's astro tenant assumes a scaffold. Treat as `own` (run its own build) unless/until a dedicated path lands.* |
+
+- Read `package.json` once (if present) + the entry HTML. The **un-built-source entry** is the decisive signal: a built `dist/index.html` referencing hashed bundles is *not* `own` to re-build blindly — but a brought-in SPA repo with `src/` + a build script is.
+- Record `frontendBuild` in orchestrator scratch (contract core, `PLAN.md` § "The Plan→Build contract"). It is **not** persisted to disk — on scratch loss it is recovered by re-reading `package.json` (this same signal).
+- Pass the resolved `frontendBuild` into the connection-plan dispatch (it tells the planner to read rendered markup for `none` vs un-built `src/**` for `own` — `CONNECTION_PLAN.md` § "What to read").
+
+## 2 · Infer the domain → capability
+
+Map the site's purpose to the Wix capability + apps using the table in `references/custom/INSTRUCTIONS.md` § "Always connect" (wedding invite → RSVP/Wix Forms; store mock → Wix Stores; **app with client/local state — todo, notes, tracker, planner — → CMS persistence swap (`@wix/data`)**; etc.). **Always connect:** if the site has no dynamic region, pick the connected feature its purpose implies; the universal floor is a Wix Forms contact/lead form — **but a client-state app maps to a CMS persistence swap, not the contact-form floor** (the connection planner detects this from source; see `CONNECTION_PLAN.md` § "(c) Persistence swap"). Also infer the **brand** (from `<title>`/copy) for scratch and any seeded-content naming.
+
+## 3 · Present a light plan, then approval
+
+Same discipline as the create path (`DISCOVERY-create.md` § "Step 3" / `PLAN-create.md`): **present the plan as its own message first, then ask for approval as a separate step.** The connect plan is *light* (no Design Direction — the user already designed it), but it still shows the user what will happen before they commit. Structure:
+
+- **What I found** — one line: the site's type/purpose + the pages/regions detected (e.g. *"A static wedding invitation — hero, date, venue, closing. No RSVP, no dynamic content."*).
+- **What I'll connect** — what you'll **wire** (existing dynamic regions → a Wix entity), what you'll **add** (the connected component the purpose implies), or what you'll **persist** (a client-state app's data layer → a Wix CMS collection), plus the **apps** to install. (e.g. *"I'll install Wix Forms and add an RSVP form styled to match the invitation."*; or *"I'll move your to-do storage into a Wix CMS collection so it persists on Wix — note it'll be shared across everyone who visits, not per-user."*)
+
+> **Persistence-swap honesty.** When the connection is a persistence swap (a client-state app), the plan must state plainly that the data is **shared/public across all visitors**, not per-user — the visitor token has no per-user identity (`INSTRUCTIONS.md` § "Scope — deferred"). Say it in the plan, before approval.
+
+Then, as a separate step, ask for approval (`AskUserQuestion`): *"Ready to connect it?"* — Options: **Yes, connect it** / **Adjust something**. If the user adjusts (different capability, skip the augmentation, etc.), handle it conversationally and re-present.
+
+> Example combined shape — present this as the plan message, then ask the approval question:
+> *"This is a wedding invitation with no RSVP. I'll install Wix Forms, add an RSVP form styled to match, and publish it live."*
+
+## 4 · After approval — hold the contract in scratch
+
+Hold the captured contract in orchestrator scratch — nothing is written to disk:
+
+- `frontend: custom`. The **`frontendBuild`** that drives Build was resolved in § 1.5 (`none` for static HTML, `own` for a framework SPA) and lives in **scratch** alongside `operation` (the in-agent contract, `PLAN.md` § "The Plan→Build contract"). `none` makes the conductor skip the build at release; `own` makes it run the project's own `npm run build` first.
+- `verticals` = the inferred capability set (e.g. `"forms"`, `"stores,ecom"`, or `"cms"` for a client-state persistence swap).
+- `brand` (from § 2) + the one-line site summary, for seeded-content naming and the end-of-run `AGENTS.md`.
+
+Then hand to `BUILD.md` — it routes Build on `frontendBuild` (`none` or `own`, from § 1.5) to `BUILD-own-build.md`. The frontend-track playbook is `references/custom/INSTRUCTIONS.md`; `PLAN-connect.md` owns the pre-approval routing.

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

@@ -0,0 +1,238 @@
+# Discovery — create operation
+
+Reached when `operation === "create"` (a create-a-new-site prompt in an empty CWD — the skill writes the site). Shared Wave-0 field resolution + CLI-auth pre-flight live in `DISCOVERY.md`; this file is the create interview → plan → approval. Run FLOW is owned by `PLAN-create.md`.
+
+Create has two framework branches (Wave 0 resolved which). The default is **`frontendBuild: wix`** (astro — the rest of this file). The minority **`frontendBuild: own`** (a framework SPA — the prompt named `vite`/`react`/`vue`/`svelte`) runs the interview + Designer but skips the astro-only steps — see § "Framework-SPA variant" at the end.
+
+---
+
+## Step 0 — Infer vertical(s) + business context
+
+The opening message usually names what they want (*"build me a skincare store"*, *"a coffee shop website"*). Extract:
+- **Vertical(s)** — which packs to load (routing table: `SKILL.md` § "When This Skill Triggers").
+- **Business / product context** — feeds brand-name suggestions, vibe options, product templates, image prompts.
+
+If too vague to infer a vertical (*"build me a site"*), ask **one conversational clarifier** (NOT `AskUserQuestion`): *"What do you want your site to do — sell things, publish content, take bookings?"* Only if you genuinely cannot infer. **Do not ask what features they want** — features follow from the vertical; the user adjusts at the plan.
+
+---
+
+## Step 1 — Brand name
+
+`AskUserQuestion`, single-select. Generate **3–4 names** relevant to the business + a "Type my own" option:
+
+> *"What should we call your brand?"*
+
+Names: short (1–3 words), memorable, mixed styles (one punchy/modern, one descriptive, one abstract); avoid generic filler. If they pick "Type my own", follow up conversationally. **If the brand is already named in the opening message, skip this step.**
+
+### After Q1 — read the loaded packs + prepare scaffold inputs
+
+The scaffold is **not** dispatched here — it fires post-approval (`BUILD-astro.md` run-step 0) so the funnel presents the plan without waiting. This section only prepares inputs.
+
+**(a) Read every pack in the resolved set, at once.** The resolved set is SKILL.md § "When this skill triggers" (third column) — e.g. a `stores` run reads `stores.md`, `cms.md`, `ecom.md`, `gift-cards.md`. `Read <SKILL_ROOT>/references/verticals/<pack>.md` for each (individual files — `Read` on the dir is `EISDIR`). Don't read the top-level pack alone then issue a second batch for its `requires:`. These preload `routes:`/`apps:`/`requires:`/`disabled` for the Step 3 plan.
+
+**(b) Scaffold inputs** — the command (dispatched later):
+
+```bash
+bash <SKILL_ROOT>/scripts/scaffold.sh <folder-name> "<brand>" --frontend astro 2> <tempfile>
+```
+
+`<frontend>` is `astro` (the only scaffolded frontend; connect/own never reach here). **Folder-name derivation** from the brand: lowercase → whitespace/punctuation runs to `-` → drop every char not `[a-z0-9-]` → trim/collapse hyphens. Must satisfy `^[a-z0-9][a-z0-9-]*$` + npm package-name validation; if the result is empty, ask the user (`AskUserQuestion`) for a folder name.
+
+- `<brand>` (original case) is sent as `--business-name` → owns the Wix project display name + URL slug. It must contain ≥1 English letter or number (CLI rejects emoji/punctuation-only — ask for a compliant brand before scaffolding).
+- `<folder-name>` controls the local dir only.
+- The script passes bare `--site-template` to stay on the blank starter non-interactively (without it `@wix/create-new` ≥0.0.72 prompts and aborts in the non-TTY shell).
+
+Examples: `"Bloom & Root"` → `bloom-root` · `"ACME, Co."` → `acme-co` · `"42 Below"` → `42-below`.
+
+---
+
+## Step 2 — Vibe
+
+`AskUserQuestion`, single-select. Generate **4 brand-personality options** tailored to the business + "Something else":
+
+> *"What's the vibe for [brand name]?"*
+
+(e.g. for jewelry: Bold & premium · Clean & modern · Warm & approachable · Something else.) If "Something else", follow up with an `AskUserQuestion` text input.
+
+---
+
+## Step 2.5 — Imagery preference
+
+Capture `imagery` in scratch — it gates AI imagery (Wix AI credits) vs CSS themed blocks. Lives only in scratch; inlined into any subagent that branches on it.
+
+**Skip rule.** If the opening prompt mentioned imagery (*"with photos"*, *"product photos"*, *"AI imagery"*, …), skip the Q3 `AskUserQuestion` and default `imagery: "ai-generated"` (re-asking feels redundant). The credit estimate + balance fetch still run for the plan's Imagery line.
+
+### 2.5.1 — Credit estimate
+
+```
+estimatedCredits =
+    1 (hero) + 2 (section decoratives) + (cms loaded ? 2 : 0)   // astro decorative term
+  + (stores loaded ? stores.productCount : 0)   // default 3 when unknown
+  + (blog loaded   ? blog.postCount      : 0)   // default 6 when unknown
+  // forms, gift-cards, and any disabled pack contribute 0
+```
+
+The integer total is what we show. Reuse the `productCount=3` / `postCount=6` defaults from "After Approval" § 1. Example — astro coffee shop (stores + cms + blog, productCount 3, postCount 6): `1 + 2 + 2 + 3 + 6 = 14`. (The `own` decorative term differs — see § "Framework-SPA variant".)
+
+### 2.5.2 — Fetch the AI-credit balance
+
+`npx @wix/cli@latest token` **without** `--site` mints an **account-scoped** token; POST it to the balance endpoint:
+
+```bash
+ACCOUNT_TOKEN=$(npx @wix/cli@latest token)   # NO --site — 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"
+```
+
+Hold `balance = response.periodicCredits.balance` and `cap = response.periodicCredits.cap`. **Fallbacks → set `balance = null` and proceed** (the estimate is unaffected; only the Q3 "Current balance" tail goes silent): `wix token` fails → surface it (a `wix login` problem); POST 401/403 → re-mint the account-scoped token once and retry (the site-scoped "never re-mint" rule does not apply — distinct cache); other 4xx / network error → log + `null`.
+
+> **Don't share the token.** The account-scoped token is account-level reads only; every site-operating call uses `npx @wix/cli@latest token --site "$SITE_ID"` (`references/shared/AUTHENTICATION.md`). The two are mutually rejected.
+
+### 2.5.3 — Ask Q3
+
+`AskUserQuestion`, two single-select options; interpolate `<estimatedCredits>` + balance:
+
+> *"How should we handle imagery?"*
+
+- **Themed blocks (Recommended)** — *"Polished CSS-only design. ~6 min build. Uses 0 Wix AI credits."*
+- **AI-generated imagery** — *"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 (don't print "unknown" — silence is the contract). Capture `imagery: "themed-blocks" | "ai-generated"` in scratch (gates consumed by `BUILD-astro.md § "Imagery gates"`).
+
+---
+
+## Craft the aesthetic direction (in scratch)
+
+From vertical + personality + audience, craft a **2–3 sentence aesthetic direction** like a designer — decide, don't ask more questions. Example: *"For Bloom & Root, an organic editorial aesthetic — Kinfolk meets a botanical garden. Warm cream backgrounds, deep forest green accents, Playfair Display + Source Sans 3, generous whitespace."* **Do NOT print it as a standalone message** — hold it in scratch and weave it into the plan's Design Direction (printing it separately detaches the most important content; keep Q2 → plan tight).
+
+## The Designer's inputs
+
+The Designer owns the design — it **authors `DESIGN.md`** (the tokens) and returns brand-voice strings; `emit-design-tokens.mjs` projects the token CSS + types from it. Inputs are **judgment-only**, produced here and held in scratch:
+- **Brand** `{name, description}` (description = the opening business context, one line).
+- **Aesthetic direction, palette, typography, mood, page color strategy** — from the craft step.
+
+**Application inputs** (loaded packs, packs-with-components, disabled packs, nav links) are **not** passed to the Designer — they feed `compose.mjs` at the bridge (`BUILD-astro.md` § "2. Setup window"). Hold them in scratch. (Nav-links for stores+cms+ecom+gift-cards: `[{"href":"/about","label":"About"},{"href":"/faq","label":"FAQ"}]` — `/about`+`/faq` when `cms` loaded; never `/products` (stores splices it), `/gift-cards` (disabled), or any route whose pack contributes a nav marker.) The orchestrator dispatches the Designer **post-approval** (`BUILD-astro.md` run-step 0); its prompt template lives in `DESIGN_SYSTEM.md`.
+
+---
+
+## Step 3 — Present the plan
+
+**Send the rendered plan as its own assistant message FIRST**, then — separately — use `AskUserQuestion` for approval. Never bundle the plan into the approval question, never replace it with a one-liner, never skip to "Ready to build?" — the user must see the rendered plan first.
+
+**Do NOT show implementation details** (scaffolding, `npm install`, `env pull`, API calls, phase agents, designer handoffs, build steps). They care about their site. Apps, packages, and CMS collection names are implementation details — not surfaced; the loaded verticals determine apps, and the seeder names collections at run time.
+
+The plan has two halves: a **decision card** (Sections A + B — what the user weighs in on) and a **technical scope** block (Section C + Imagery — "for free" from the loaded packs, skimmable).
+
+**Section A — Design Direction** (lead): the aesthetic paragraph, then a compact block — aesthetic tone · palette (2–3 colors + hex) · type pairing (display + body) · mood/key visuals · page color strategy (Uniform Light / Uniform Dark / Defined Hybrid).
+
+**Section B — Features**: 1–2 line bullets of user-facing functionality per pack; tag CMS-powered ones **(CMS-based)**. **Skip features from `disabled: true` packs** (today: `gift-cards`) — the code still ships (page + nav/home contributions) but the plan stays silent until the user enables the app. Non-disabled packs (incl. transitive ones like ecom) contribute normally.
+
+After Section B, emit a `---` and one line: *"Technical scope below — auto-decided from the features above. Skim if you want; not required reading."*
+
+**Section C — Pages.** Emit this header exactly, then one row per loaded pack's `routes:` entry:
+
+```
+| Page | Route | Source |
+|------|-------|--------|
+```
+
+Compose rows from each loaded pack's `routes:` array (top-level + transitive via `requires:`) — don't hardcode, omit, or invent rows. **Skip every route from a `disabled: true` pack** (today `gift-cards`'s `/gift-cards` does not appear; the file still ships for instant dashboard activation). Per surviving entry:
+- **Page** — the entry's `name:` if present, else derive from the path: `"/"`→`Home`; `"/<seg>/[slug]"`→title-case(seg, singular)+" Detail"; else title-case the last static segment, `-`→space (`/thank-you`→`Thank You`).
+- **Route** — the `route:` value verbatim (or the literal `Hosted by Wix` for path-less Wix-hosted endpoints).
+- **Source** — top-level pack with non-empty `apps:` → `apps[0].name`; transitive pack → walk up the `requires:` chain to the top-level puller's `apps[0].name` (so ecom's `/cart` shows `Wix Stores`); `cms` → literal `CMS (builtin)`. No `(auto)`/`(passive)` suffixes.
+
+**Order rows by user-facing flow:** CMS pages first (Home, About, FAQ), then catalog/content, then transactional (cart, thank-you, checkout). Within a pack, preserve `routes:` declaration order.
+
+**Imagery line** — one line below Section C: `**Imagery:** Themed blocks`, or `**Imagery:** AI-generated (~<estimatedCredits> Wix AI credits)` when Q3 captured `ai-generated`. Don't repeat the balance (shown at Q3).
+
+### Example (skincare ecommerce)
+
+```markdown
+Here's my plan for **Bloom & Root**:
+
+## Design Direction
+
+For Bloom & Root, **clean luxury with organic warmth** — a curated boutique
+where every product feels considered. Warm cream backgrounds, deep charcoal
+text, rose gold accents. Cormorant Garamond headlines + DM Sans body.
+
+- **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
+
+## Features
+
+- **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.
+
+---
+
+*Technical scope below — auto-decided from the features above. Skim if you want; not required reading.*
+
+## 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    |
+
+**Imagery:** Themed blocks
+
+Should I proceed?
+```
+
+(Cart/Thank You/Checkout show `Wix Stores`, not "Wix eCommerce" — ecom is transitive via stores's `requires:`; the user opted into "selling things".)
+
+### Approval
+
+`AskUserQuestion`: *"Ready to build?"* — **Yes, build it** / **Adjust something**. If they adjust, handle it conversationally (swap brand, change vibe, add/remove a page), re-present the plan, re-ask.
+
+---
+
+## After Approval — capture intent in scratch
+
+On "Yes, build it", hold the captured intent (brand, frontend, verticals, the per-vertical intent block) in scratch — **nothing is written to disk**. The transition into Setup is FLOW, owned by `PLAN-create.md` (which hands off to `BUILD-astro.md`).
+
+Build a single intent JSON in scratch (only blocks for loaded verticals); seeders receive the relevant `intent.<pack>` slice inlined (`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:
+- **`imagery`** — exactly the Step 2.5 value.
+- **`stores.productCount`** — implied count (*"a few candles"*→3, *"a full catalog"*→8); default 3. **`categoriesNamed`** — explicitly-named strings only; else `[]`.
+- **`cms.collections`** — one per CMS-driven page (≥ `{purpose:"about"}` + `{purpose:"faq"}` for any cms run); `itemCount` only when a number was implied.
+- **`blog.postCount`** — implied count, default 6; **`topics`** explicit-only.
+- **`forms.forms`** — one per described form; `purpose` ∈ contact/signup/lead/…; `fields` explicit-only.
+- **`gift-cards.enabled`** — `true` only when explicitly asked; else omit.
+
+When in doubt, omit a field rather than fabricate. Discovery's domain work ends here — nothing on disk; `PLAN-create.md` owns the handoff.
+
+---
+
+## Framework-SPA variant (`frontendBuild: own`)
+
+When Wave 0 resolved `frontend: custom`, `frontendBuild: own` (an explicit framework keyword on a create prompt): run the **vibe (Step 2)**, the **imagery question (Step 2.5)**, and the **Designer** — its `DESIGN.md` + `.wix/design-tokens.css` are framework-agnostic, so the brand look is real here too, and both image phases apply (decoratives land in the SPA hero/about via `src/decorative-images.json`; entity images PATCH Wix entities). **Skip the astro-only steps:** no `scaffold.sh`, no astro Design-Direction card / Pages table, no `compose.mjs`.
+
+- **Infer** brand + vertical/capability (same routing as astro) + the named framework (vite+react / vue / svelte).
+- **Plan** (its own message, then approve — same discipline as `DISCOVERY-connect.md` § 3): *what I'll build* (a small \<framework\> app with the brand's look — palette + type as CSS custom properties; full per-component composition is framework-default for now) + an **`Imagery:`** line + *what I'll connect* (capability → its Wix backend) + the apps. For a client-state capability, state the **shared-data caveat** up front.
+- **Credit estimate decorative term** is `1 (hero) + 1 (about) = 2, fixed` (the minimal SPA emits exactly `["hero","about"]`, no `/about`+`/faq` route headers — drop the cms `+2`). Example — bakery in react+vite (cms + stores, productCount 3): `2 + 3 = 5`.
+- **On approval** hold the contract in scratch (`frontend: custom`, `frontendBuild: own`) → `BUILD.md` routes on `frontendBuild: own` → `BUILD-own-build.md` (create × own: Designer + `emit-design-tokens.mjs` → scaffold the framework → `init` → generate the minimal app importing `.wix/design-tokens.css` → wire a fresh `@wix/data` module → the project's own build + release).