@hostinger/mcp 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ Generated at release time from the diff between the previous and current
 build. Tool changes are listed individually; everything else is summarised
 by area.
 
+## v3.3.1 — 2026-10-19
+
+### Also in this release
+
+- Bundled agent skills: 15 files
+- Other files: `src/core/skills.js`, `src/core/skills.ts`
+
 ## v3.3.0 — 2026-10-19
 
 ### Also in this release

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Hostinger API — manage domains, DNS, hosting, VPS, billing and more from Gemini CLI.",
   "mcpServers": {
     "hostinger": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostinger/mcp",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "mcpName": "io.github.hostinger/hostinger-api-mcp",
   "description": "MCP server for Hostinger API",
   "repository": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/hostinger/api-mcp-server",
     "source": "github"
   },
-  "version": "3.3.0",
+  "version": "3.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@hostinger/mcp",
-      "version": "3.3.0",
+      "version": "3.3.1",
       "transport": {
         "type": "stdio"
       },

package/skills/headless/SKILL.md

@@ -9,7 +9,7 @@ description: "Orchestrator for the Hostinger Headless build flow — build and d
 
 You are an AI coding agent. The user pasted a short prompt that points you here — something like:
 
-> Build a Headless site for `example.com` using hostinger.com/ai/skill.md
+> Build a Headless site for `example.com` using hostinger.com/headless/skill.md
 
 Your job is to build and deploy a real website on the user's Hostinger account by following this
 recipe and the recipes it links to — nothing more, nothing less.
@@ -21,7 +21,7 @@ holds the flow, the state contract, the failure policy and the guardrails.
 
 The pasted prompt contains exactly two things that matter:
 
-- **This URL** — `hostinger.com/ai/skill.md`, the stable entry point.
+- **This URL** — `hostinger.com/headless/skill.md`, the stable entry point.
 - **A domain** — e.g. `coral-pottery-1847.hostingersite.com` (a temporary Hostinger subdomain) or
   the user's own purchased domain. This is the single site you may touch.
 
@@ -37,47 +37,48 @@ Hostinger connector's OAuth token. **This recipe is not a security boundary.**
 ## The flow stages - STEPS TO FOLLOW
 
 Work through the steps in the order below, each reading its recipe and writing its artifact into the
-site workspace `~/.hostinger/<domain>/`. The order is a **dependency order, not a strict lockstep**:
-**provision runs as a background task** and the prepare work of the stages around it overlaps the wait
-(see *Background provision & the instance barrier* below). Never skip a stage — **except validate**
-(optional) **and content model for a `webapp` brief** (there is no CMS or store to seed — see step 4):
-every other stage self-verifies and deploy verifies the live result, so validate is a
-quick instance+API confirmation and its rebuild/preview/approval run only when a person is signing off
-(see its recipe). State files are only hints; the truth is what the Hostinger connector reports, so
-verify a "done" marker against reality before acting on it. If a step's `SKILL.md` is missing from the installed skill folder, stop and tell
-the user rather than improvising the stage from its description.
+site workspace `~/.hostinger/<domain>/`. 
+
+
+The order is sequencial run and check the whole headless flow:
+
+| # | Stage                                                                                                              | Skill / source                                                        | Writes | Instance? |
+|---|--------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|---|---|
+| — | **connect** — connect the Hostinger connector, auth, get active plan                                               | `connect/SKILL.md` → `connect/tools/<tool>.md` | `connect.json` | no |
+| 1 | **check state** — where does this domain stand? resume / switch / start over                                       | `steps/01-check-state/SKILL.md`                                       | `state.json` | no |
+| 2 | **refine** — discover what the user wants, in conversation                                                         | `steps/02-refine/SKILL.md`                                            | `brief.md` | no |
+| 3 | **provision** — choose the backend from the brief, then provision it                                               | `steps/03-provision/<backend>/SKILL.md`                               | `site.json` | **bg** — fire, then poll in the background |
+| 4 | **content model** — define + create content/images, then push to the backend                                       | `steps/04-content-model/<backend>/SKILL.md`                           | `content-model.md` | prepare: no · **push: yes** |
+| 5 | **design** — derive design directions from the brief, pick one, write the `design.md` contract + logo              | `steps/05-design/SKILL.md`                                            | `design.md`, `brand/` | no |
+| 6 | **frontend** — pick/confirm the framework (default Next.js SSR), implement `design.md` against the backend         | `steps/06-frontend/SKILL.md`                                          | source in `<workspace>/src/` | shell: no · **data: yes** |
+| 7 | **validate** *(optional)* — quick instance+API confirmation; rebuild/preview/approval only when a person signs off | `steps/07-validate/SKILL.md`                                          | — | no (local) |
+| 8 | **deploy** — upload source, trigger the build                                                                      | `steps/08-deploy/SKILL.md`                                            | `deploy.json` | **yes** |
+| 9 | **done** — hand over URLs, dashboard, summary, next steps (the **final report**)                                   | `steps/09-done/SKILL.md`                                              | — | no |
 
-**The one concurrency rule:** two *independent* stages in a single session may run at once, but never
+**The most important is that connect stage runs first and always**
+It's fetched from the public URL and runs *before* the Hostinger MCP Server
+is loaded, the main goal of this is to have the Hostinger MCP Server.
+
+You can find those connect skills under `connect/`.
+The main skill lives in `connect/SKILL.md`.
+There are also specific tools under `connect/tools/`.
+
+The other 9 numbered steps live under `steps/` and are read from the installed skill folder (this will be guided in connect step).
+
+**One concurrency rule:** two *independent* stages in a single session may run at once, but never
 two writers of the same artifact, and never two agents/windows on the same domain — the `.lock`
 (Step 1) guards that. Parallelism is always *optional*: an agent that can't interleave work runs the
-steps serially and is still correct.
-
-The **Instance?** column says whether a stage touches the live backend: `no` = pure prepare work that
-can run during the provision wait; `push`/`data`/`yes` = a commit phase that joins the instance
-barrier; `bg` = provision itself, the background task.
-
-| # | Stage | Skill / source | Writes | Instance? |
-|---|---|---|---|---|
-| — | **connect** — connect the Hostinger connector, auth, active plan | `connect/SKILL.md` → `connect/tools/<tool>.md` | `connect.json` | no |
-| 1 | **check state** — where does this domain stand? resume / switch / start over | `steps/01-check-state/SKILL.md` | `state.json` | no |
-| 2 | **refine** — discover what the user wants, in conversation | `steps/02-refine/SKILL.md` | `brief.md` | no |
-| 3 | **provision** — choose the backend from the brief, then provision it | `steps/03-provision/<backend>/SKILL.md` | `site.json` | **bg** — fire, then poll in the background |
-| 4 | **content model** — define + create content/images, then push to the backend | `steps/04-content-model/<backend>/SKILL.md` | `content-model.md` | prepare: no · **push: yes** |
-| 5 | **design** — derive design directions from the brief, pick one, write the `design.md` contract + logo | `steps/05-design/SKILL.md` | `design.md`, `brand/` | no |
-| 6 | **frontend** — pick/confirm the framework (default Next.js SSR), implement `design.md` against the backend | `steps/06-frontend/SKILL.md` | source in `<workspace>/src/` | shell: no · **data: yes** |
-| 7 | **validate** *(optional)* — quick instance+API confirmation; rebuild/preview/approval only when a person signs off | `steps/07-validate/SKILL.md` | — | no (local) |
-| 8 | **deploy** — upload source, trigger the build | `steps/08-deploy/SKILL.md` | `deploy.json` | **yes** |
-| 9 | **done** — hand over URLs, dashboard, summary, next steps (the **final report**) | `steps/09-done/SKILL.md` | — | no |
-
-**connect** runs first — it's fetched from the public URL and runs *before* the Hostinger connector
-exists. The nine numbered steps live under `steps/` and are read from the installed skill folder.
-**provision** and **content model** route to a per-backend subfolder (`<backend>` = `wordpress` |
-`ecommerce` | `webapp`), chosen from the brief. **`webapp`** is a plain Node.js app host (an empty
-website — no CMS, no store, no `/cms`) for any app/SPA that brings its own code and data; it **skips the
-content-model stage entirely** (there is nothing to seed — the app owns its own data) and never installs
-WordPress. **design** turns the brief into a chosen look and writes the `design.md` contract;
-**frontend** is a single generic step that picks the framework (guess → default Next.js SSR → confirm)
-and implements `design.md`.
+steps serially and is still correct. Saying this, Always that you consider, you can run the steps
+in parallel using different threads or processes to save time, but always ensure the right output.
+
+Steps can generate **State files** those files are only hints; the truth is what the Hostinger connector reports, so
+verify a "done" marker against reality before acting on it. If a step's `SKILL.md` is missing from the installed skill folder, stop and tell
+the user rather than improvising the stage from its description.
+
+The **Instance?** column says whether a stage touches the live backend:
+`no` = pure prepare work that can run during the provision wait;
+`push`/`data`/`yes` = a commit phase that joins the instance barrier;
+`bg` = provision itself, the background task.
 
 **Always end with the final report.** Whenever a run ends, give the user the final report defined
 in `steps/09-done/SKILL.md`: an outcome paragraph, a *Steps completed* table (one row per stage that
@@ -97,38 +98,35 @@ Validation before deploy, always — nothing reaches the live domain unseen.
 
 ### Background provision & the instance barrier
 
-Provisioning is mostly *waiting*: `hosting_websites_create` returns "queued" immediately, then it's a
-`hosting_websites_list-setups` poll every ~15 s for a few minutes. Don't block on that poll. The
+**Provision always runs — what it does depends on what the domain already has.** Often onboarding on
+hostinger.com has already created the website before you run, so the domain *has* a headless instance;
+but an instance existing does **not** mean provision is done or can be skipped. `check_state` works out
+which of these cases applies and records it, then provision takes the matching path:
+
+1. **An empty headless shell already exists for the domain (the common onboarding case).** Onboarding
+   creates the website first — an **empty headless shell** (`hosting_websites_start-setup { type:
+   "headless_empty" }`): `website_type` is `headless`, but **no backend is installed** (no WordPress at
+   `/cms`, no store). This still goes through provision, which **adopts the shell and swaps it to the
+   chosen backend** (the backend is picked in refine first): WordPress is installed into the shell's
+   `/cms` with `wordpress_installations_install { type: "headless" }`, or the shell is adopted as the
+   Ecommerce storefront host. **Never skip provision for a shell, and never create a second site.** See
+   the provision router's *Onboarding handoff*.
+2. **No instance exists at all** (the user ran the headless flow without onboarding provisioning
+   anything). Provision creates a fresh headless instance with `hosting_websites_start-setup` using the
+   chosen backend's own `type`.
+3. **User wants a webapp.** Provision is a plain Node.js app host, not headless — `webapp` ignores
+   headless shells entirely and is only reached by experimental actions, never the onboarding flow.
+
+Either way the create/install is asynchronous and returns `queued` immediately, then it's polled
+every ~15 s for a few minutes — **what you poll depends on the path**: a fresh
+`hosting_websites_start-setup` is polled with `hosting_websites_list-setups` until `completed`, while a
+shell swap (`wordpress_installations_install`) creates no new setup, so it's polled with
+`wordpress_installations_list` until the `/cms` row is `is_valid`. Don't block on that poll. The
 single rule that makes the overlap safe:
 
 > **Fire provision as a background task, then do every stage's prepare work while it settles. The
-> moment a step must write to the live instance, it waits for provision to report `completed`
-> (verified against `hosting_websites_list-setups`). That wait is the *instance barrier*.**
-
-Once `brief.md` exists (it already fixes the backend choice), the lanes are:
-
-```
-refine ──▶ brief.md
-             ├─▶ provision: FIRE create, record provision.in_progress ─────────┐  (bg poll)
-             ├─▶ content-model PREPARE: define entities, write copy,           │
-             │             generate images                                      │
-             ├─▶ design: directions → design.md + logo (from the brief)        │
-             └─▶ frontend SHELL: pick framework, scaffold, implement design.md │
-                                                                                │
-   ══════════════════════ instance barrier: provision.status == completed ═════╪═════
-                                                                                ▼
-             ├─▶ content-model PUSH: send content/media via the connector (needs the instance)
-             └─▶ frontend DATA: wire fetch/bind against the backend API URL from site.json
-                           │
-                           ▼
-                        validate ──▶ deploy (needs the provisioned target) ──▶ done
-```
-
-Nothing before the barrier touches the backend, so it's safe to run in any order the agent can manage
-— sequentially if it can't interleave. Nothing after the barrier may start until provision is
-verifiably `completed`. If provision **fails** at the barrier (quota, `422`, a changed free
-subdomain), the prepare artifacts (drafted content, generated images, the `src/` shell) stay valid —
-only the commit phases wait or retry; re-run provision, then cross the barrier.
+> moment a step must write to the live instance, it waits for provision to report ready (via the
+> backend step's readiness poll — see above). That wait is the *instance barrier*.**
 
 ---
 
@@ -264,4 +262,4 @@ result:
 
 Never edit the JSON before sending, never add account details (the connector's login identifies the
 account), and never let a failed send block, delay or change the run. Check-state sends any
-reports still unsent (abandoned runs, earlier failures) with `unsent`.
+reports still unsent (abandoned runs, earlier failures) with `unsent`.

package/skills/headless/connect/SKILL.md

@@ -89,13 +89,8 @@ for that tool, or drive `npx --yes --package=@hostinger/mcp@latest hostinger-api
 
 ## Phase 3 - Continue to Headless Hosting steps
 
-After evrything is verified then you can go back to `headless/SKILL.md` and follow the steps section to start the process.
+After evrything is verified and you have access to the Hostinger MCP Server and the skills then you can go back to `headless/SKILL.md` and follow the steps section to start the process.
 
-> **Backend-specific MCP groups.** The base connector covers hosting + WordPress. An **Ecommerce** build
-> also needs the separate **`hostinger-ecommerce`** MCP group (`ecommerce_*` ops) — it is not loaded by
-> default. The provision step adds it when the brief chooses Ecommerce (see
-> `steps/03-provision/ecommerce/SKILL.md`); adding an MCP server needs a session restart/reconnect to
-> take effect.
 
 ## Reference Sources
 

package/skills/headless/steps/01-check-state/SKILL.md

@@ -5,7 +5,7 @@ description: "First build step of the Hostinger Headless flow, run right after c
 
 # headless-step-check-state
 
-The first build step of the Hostinger Headless flow (orchestrated by `hostinger.com/ai/skill.md`),
+The first build step of the Hostinger Headless flow (orchestrated by `hostinger.com/headless/skill.md`),
 run right after connect. Connect has already connected the Hostinger connector and confirmed the
 account can build. Your job here is to
 **figure out where this domain stands and agree the route with the user** before any new work begins.
@@ -116,6 +116,17 @@ Query the Hostinger connector — the local files are never trusted on their own
   - `status: completed` → provisioned; then, depending on backend, check whether a build has succeeded.
   - `status: running` → still provisioning (see Step 1).
   - `status: failed` → provisioning stopped before finishing → route to **provision** to self-heal.
+- **Is it an empty headless shell from onboarding?** A `headless` site whose setup is `completed` is
+  **not necessarily finished** — onboarding now creates the website *before* the build runs, as an
+  **empty headless shell** (`hosting_websites_start-setup { type: "headless_empty" }`): `website_type`
+  is `headless` but **no backend is installed** (no WordPress at `/cms`, no store). Tell a shell from a
+  real backend the same way provision does: within 24 h the setup `type` is `headless_empty`; otherwise
+  `wordpress_installations_list { username, domain, ownership: "all" }` returns **no** `/cms` row and
+  there is no `site.json` recording a backend. An empty shell means **provision has not chosen or
+  installed a backend yet** — this is a **new build** that happens to already own its website, not a
+  finished or resumable one. Route it to **refine** (choose the backend), then **provision** adopts the
+  shell and swaps it to that backend (see the provision router's *Onboarding handoff*). Never create a
+  second site, and never skip provision for it.
 
 Reconcile with the local state. **When they disagree, reality wins** and the local `stage` is
 corrected.
@@ -132,7 +143,8 @@ yet** (`brief.md`, `site.json`, …).
 | Local state | Reality (domain) | Position |
 |---|---|---|
 | none (connect only) | free | **new build** — start from refine |
-| none (connect only) | site exists | **adopt / resume** — never create a second site; route to the first unfinished stage |
+| none (connect only) | empty headless shell (onboarding) | **new build on an existing shell** — start from refine; provision adopts the shell and swaps it to the chosen backend. Never create a second site, never skip provision |
+| none (connect only) | site exists with a real backend | **adopt / resume** — never create a second site; route to the first unfinished stage |
 | build artifacts present, incomplete | matches | **resume** at `state.json`'s `stage` |
 | build artifacts present | disagrees | **reality wins** — recompute the stage from what actually exists |
 | build artifacts present, all done | live site exists | **finished** — this is now an *iterate* request, not a build |
@@ -145,12 +157,16 @@ The question to ask depends on whether there is actually **something to resume**
 artifacts** (`brief.md`, `site.json`, …) or a **live site** for this domain. A stray `.lock` or
 connect-only files are *not* something to resume.
 
-- **New build** (no build artifacts and the domain is free) → just proceed to refine. **Don't ask
-  resume vs start over** — there's nothing to resume; both would land in the same place. If a leftover
-  `.lock` is lying around, silently take it over and continue (optionally mention it in one line).
-- **Something to resume** (build artifacts exist, or a site exists for the domain) → tell the user
-  plainly what's there and **ask them to choose**, regardless of how old it is (don't guess from
-  timestamps):
+- **New build** (no build artifacts and either the domain is free **or** it holds only an empty
+  headless shell from onboarding) → just proceed to refine. **Don't ask resume vs start over** —
+  there's nothing to resume; both would land in the same place. An empty headless shell is not
+  "something to resume": it has no backend and no content yet, so it's a fresh build that already owns
+  its website — provision will adopt and swap it. Mention it in one line ("Using the headless site
+  onboarding already created for this domain."). If a leftover `.lock` is lying around, silently take
+  it over and continue (optionally mention it in one line).
+- **Something to resume** (build artifacts exist, or a site exists for the domain **with a real backend
+  installed** — WordPress at `/cms`, a store, or a deployed app) → tell the user plainly what's there
+  and **ask them to choose**, regardless of how old it is (don't guess from timestamps):
 
 - **Resume** — pick up at the computed stage. (If a `.lock` is present in this case, also confirm no
   other window is actively building this domain right now.)

package/skills/headless/steps/02-refine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: headless-step-refine
-description: "Step 2 (refine) of the Hostinger Headless flow. Turns the user's seed — often just a domain — into a brief through conversation: asks what they want to build (purpose, audience, tone, pages, products, must-haves; images, local files, links all welcome), recommends the backend that fits (WordPress, Ecommerce, WordPress + Ecommerce, or Webapp for a custom app/SPA), lets the user confirm it, then writes brief.md."
+description: "Step 2 (refine) of the Hostinger Headless flow. Turns the user's seed — often just a domain — into a brief through conversation: asks what they want to build (purpose, audience, tone, pages, products, must-haves; images, local files, links all welcome), then *infers* the backend that fits (WordPress, Ecommerce, WordPress + Ecommerce, WordPress + WooCommerce for a one-site content+store, or Webapp for a custom app/SPA) — it never asks the user to pick a backend or a technology; the user confirms the plan in plain language, then it writes brief.md. Hostinger Ecommerce stays the default for selling; WooCommerce is chosen only when the user explicitly asks for it or wants content and a store on one WordPress site."
 ---
 
 # headless-step-refine
@@ -13,6 +13,14 @@ the site comes from talking to the user.
 backend. Every other question is skippable: the more the user gives, the better the site, but never
 hold the build hostage to refinement. Fill gaps with sensible defaults and say so in the brief.
 
+> **Never ask the user to choose a backend or a technology.** Don't ask "WordPress or Ecommerce?",
+> don't present WordPress/Ecommerce/WooCommerce/Webapp as options, and don't surface the backend in a
+> multiple-choice UI. Open with **"What do you want to build?"** and infer the backend yourself in
+> Step 4 from what they describe (and whether they sell). The backend is a technical decision the flow
+> makes *for* the user — they confirm the **plan** (what the site is and does), not the plumbing. The
+> only exception is when the user *volunteers* a backend ("build it on WordPress", "use WooCommerce"):
+> then honour their choice and note it in the brief.
+
 **In:** the domain (the workspace directory name), plus anything the user already shared.
 **Out:** `~/.hostinger/<domain>/brief.md`.
 
@@ -36,21 +44,38 @@ Suggested backend on a provisioned site. Explain that switching backends means a
 
 Before asking anything, collect what the user has already given you, so you don't ask for it again:
 
+- **Inspect the directory the command was run in** — this is the biggest signal for the build mode
+  (Step 3). Look for an existing **frontend / webapp / commerce project**: a `package.json`, a
+  framework config (`next.config.*`, `astro.config.*`, `vite.config.*`, `svelte.config.*`, `nuxt.*`),
+  a `src/` or `app/` tree, `index.html`, a storefront/cart, etc. A real project here usually means the
+  user **already has their own frontend** and mainly needs a Hostinger backend to wire it to — lean
+  toward "bring your own frontend" in Step 3. If the folder has nothing site-like, assume they don't
+  and lean toward "agent builds it".
 - Anything in the pasted prompt beyond the domain (a sentence, a link, a screenshot).
 - Files in the current project that look like site material (copy, logos, product lists, images).
-- What the agent already knows about the user from local memory or this conversation.
+- What the agent already knows about the user from local memory or this conversation (a prior build,
+  stack preferences, a frontend they always use).
 - The domain name itself — a hint only (`coral-pottery.com` suggests pottery), never a conclusion.
 
 ## Step 3 — Ask
 
-If Step 2 already answers *what are you building* and *will they sell*, skip straight to Step 4.
+If Step 2 already answers *what are you building* and *will they sell*, skip the Round 1–3 questions
+below, but still ask **Build mode** before moving on.
+
+Otherwise open with one line and **wait for the user's answer**: *"Tell me what you want to build — a
+sentence is enough. Links, screenshots or files help too. Skip anything you don't want to answer."*
 
-Otherwise open with one line: *"Tell me what you want to build — a sentence is enough. Links,
-screenshots or files help too. Skip anything you don't want to answer."*
+> **"What do you want to build?" is an OPEN question — ask it in plain prose and wait.** Never turn it
+> into a multiple-choice list of pre-baked site ideas ("Coffee shop / Travel blog / Portfolio …"):
+> that puts words in the user's mouth and defeats the point of asking. Let them describe it in their
+> own words. The structured question UI is only for genuinely *choice-shaped* follow-ups (selling
+> yes/no, which pages, tone adjectives, the build mode) — not for the opening question, and never for
+> the backend.
 
 Ask in **short rounds of 2–3 questions**, and adapt each round to the previous answers. If your tool
 has a structured question UI (multiple choice with an "other" field), use it for the choice-shaped
-questions. **At most 3 rounds**, and stop early as soon as you can guess the backend and the user
+follow-up questions (pages, selling yes/no, tone) — **never for the opening "what do you want to
+build?" and never for the backend** (that's your decision, not theirs). **At most 3 rounds**, and stop early as soon as you can guess the backend and the user
 seems done — "just build it", "you decide", or a skipped question means *use defaults*, not *ask
 again*.
 
@@ -84,15 +109,38 @@ If the user asks for something outside the scope (user accounts, member areas, b
 calendar backend, user-generated content), say plainly that the headless flow doesn't support it yet
 and record it under **Out of scope** — don't promise it.
 
-## Step 4 — Recommend the backend
+### Build mode — ask once (this one *is* a user choice)
+
+The backend is your call, but **how the frontend gets built is the user's** — because most of the time
+the user already has their own frontend and just needs a Hostinger backend to wire it to. After the
+folder + memory inspection (Step 2), ask **one** question (a structured choice is ideal here), seeding
+the default from what you found:
+
+- **Bring your own frontend** *(default when Step 2 found a real project in the folder)* — "I already
+  have a frontend / I'll drive the design and we vibe-code it together." The agent **uses the user's
+  existing project in the current folder as the source**, collaborates on design/code at the user's
+  direction, and wires it to the provisioned backend. There is **no agent-generated design** — the
+  design step defers to the user (see the Build mode box at the top of the design step), and the frontend step builds on their project
+  rather than scaffolding a new one.
+- **Agent designs and builds it** *(default when the folder has nothing site-like)* — "Give me ideas
+  — you design and code it." Today's flow: the design step proposes directions and the frontend step
+  scaffolds and implements them.
 
-Pick the backend that fits what the user told you:
+Record the answer as the brief's **Build mode**. This is the one frontend/technology question you *do*
+put to the user; everything else about the stack (framework, SSR/SSG) is still inferred. The deliverable
+is the same either way — a working site on the backend; only *who drives the frontend* changes.
+
+## Step 4 — Decide the backend (your call, from the brief — not a question)
+
+From what the user described, **you** pick the backend that fits — this is an internal decision, never
+a question put back to the user. Pick the backend that fits what the user told you:
 
 | Backend | Choose when | What it gives the owner |
 |---|---|---|
 | **WordPress** | No selling. The owner publishes and edits content: pages, blog, articles, portfolio. | Headless WordPress at `/cms` — write and edit content in wp-admin. |
 | **Ecommerce** | Selling is the point, and the rest is a few static pages (About, Contact, FAQ, policies). No ongoing blog. | Hostinger Ecommerce store — products, collections, checkout, payments, shipping, orders. |
-| **WordPress + Ecommerce** | Selling **and** regular editorial content (a blog, guides, lookbooks, recipes) the owner keeps adding to. | Both: WordPress for content, the Ecommerce store for products and checkout. |
+| **WordPress + Ecommerce** | Selling **and** regular editorial content (a blog, guides, lookbooks, recipes) the owner keeps adding to, run as **two** backends (WordPress site + separate Hostinger Ecommerce store). | Both: WordPress for content, the Ecommerce store for products and checkout. |
+| **WordPress + WooCommerce** | **Only** when the user explicitly names WooCommerce, or explicitly wants content **and** a store on **one** WordPress site (one admin, one domain). The one-site alternative to WordPress + Ecommerce. | A single headless WordPress at `/cms` with the WooCommerce plugin — products, cart, coupons and checkout (Cash on Delivery) over the WooCommerce Store API, plus WP posts/pages on the same site. |
 | **Webapp** | A custom **app, SPA or web application** that brings its own code and data — a dashboard, tool, calculator, booking app, a project the user is deploying — **not** a content site or a store. No CMS and no store engine. | A plain Node.js app host (an empty website, no `/cms`), with a MySQL database when the app needs one. The app owns all its routes and data. |
 
 Rules of thumb:
@@ -104,6 +152,12 @@ Rules of thumb:
   WordPress + Ecommerce.
 - **Then the content.** Selling plus only a few fixed pages → Ecommerce. Selling plus content the
   owner will keep publishing → WordPress + Ecommerce.
+- **Hostinger Ecommerce is the default for selling — WooCommerce is never the default and is never
+  recommended on its own.** Choose **WordPress + WooCommerce** only when the user explicitly names
+  WooCommerce, or explicitly wants content **and** a store on one WordPress site (one admin, one
+  domain — the one-site alternative to WordPress + Ecommerce). For every other selling case, keep
+  Hostinger Ecommerce. If the user wants both content and a store but hasn't said "one site" or
+  "WooCommerce", offer it as an option — don't switch to it silently.
 - **Don't add WordPress "just in case".** A second backend is a second admin to learn. Recommend the
   combination only when the user described ongoing content.
 - Selling a single service by enquiry (no checkout, no cart) is **not** commerce → WordPress with a
@@ -114,22 +168,26 @@ Rules of thumb:
 
 **Then set rendering** (write it in the brief's **Rendering** section): **Ecommerce → SSR required**
 (carts/search need per-request rendering — any SSR framework works; Next.js is the default, not a
-requirement); **WordPress → SSG (Astro)** if the site is mostly static and the owner is fine rebuilding
+requirement); **WordPress + WooCommerce → SSR required** (same reason — cart/checkout need per-request
+rendering); **WordPress → SSG (Astro)** if the site is mostly static and the owner is fine rebuilding
 to publish, otherwise **SSR**; **Webapp → whatever the app is** (SSR for a server app, SPA for a
 client-only app) — it deploys as a Node.js app either way. When unsure, default to **Next.js SSR**.
 
-## Step 5 — Confirm in one message
+## Step 5 — Confirm the plan in one message
 
-Send **one** message that carries both the recommendation and the brief summary:
+Send **one** message that confirms **what you'll build** — the plan, not the plumbing. Lead with the
+site, not the backend:
 
-- **Backend** — the choice, the one-line reason, and what it means day to day (where they'll edit
-  content and products). Name the alternative if it was a close call.
-- **Brief** — what it is, audience, pages, products (if any), tone. Mark anything you defaulted
+- **The plan** — what it is, audience, pages, products (if any), tone. Mark anything you defaulted
   (*"assumed: warm, minimal look"*) so the user sees what they skipped.
+- **How it's built** — state the backend as a *consequence* in one plain line, focused on what it
+  means for them day to day ("I'll build this on WordPress, so you edit pages and posts in a normal
+  WordPress admin"), **not** as a choice you're asking them to make. Don't ask "is WordPress OK?" or
+  offer alternatives unless it was a genuine close call *and* the difference matters to the user.
 
 End with *"Good to go, or anything to change?"* A yes (or silence-equivalent like "go") → write
-`brief.md`. Changes → apply them and write it; don't loop back into questions. If they pick a
-different backend, use theirs and note it in the brief.
+`brief.md`. Changes → apply them and write it; don't loop back into questions. If the user
+*volunteers* a different backend, use theirs and note it in the brief.
 
 ## Step 6 — Write `brief.md` and hand off
 
@@ -139,8 +197,10 @@ user's own words where you can. Then update `state.json`:
 `"stage": "provision"`, fresh `updated_at`.
 
 The **Suggested backend** section is the contract with `03-provision/SKILL.md`, which routes on it.
-Its first line must be exactly one of `**WordPress**`, `**Ecommerce**`, `**WordPress + Ecommerce**` or
-`**Webapp**`, followed by an em dash and the one-line reason.
+Its first line must be exactly one of `**WordPress**`, `**Ecommerce**`, `**WordPress + Ecommerce**`,
+`**WordPress + WooCommerce**` or `**Webapp**`, followed by an em dash and the one-line reason.
+`**WordPress + WooCommerce**` is the WordPress backend with the WooCommerce store turned on — provision
+routes it to the `wordpress` subfolder with the store enabled (it is **not** a separate backend).
 
 ## `brief.md` template
 
@@ -184,14 +244,21 @@ user didn't specify.>
 <logo, colours, photos, copy the user provided and where they are; "None yet" if none>
 
 ## Suggested backend
-**<WordPress | Ecommerce | WordPress + Ecommerce | Webapp>** — <one-line reason>.
+**<WordPress | Ecommerce | WordPress + Ecommerce | WordPress + WooCommerce | Webapp>** — <one-line reason>.
 <"Confirmed by the user." or "User chose this over the recommended <X> because <reason>.">
 
+## Build mode
+**<Bring your own frontend | Agent designs and builds>** — <one line>. <When "Bring your own frontend":
+the path to the user's existing project in the current folder (the frontend source), and how they want
+to drive design/code. When "Agent designs and builds": leave the design + frontend steps to run as
+normal.> The design step and the frontend step both read this: **Bring your own frontend** → design
+defers to the user and frontend builds on their project; **Agent designs and builds** → both run as normal.
+
 ## Rendering
-**<SSR | SSG>** — <reason>. Rules: **Ecommerce requires SSR** (carts/search need per-request
-rendering — any SSR framework works; Next.js is the default, not a requirement); **WordPress may be
-SSG (Astro)** when the site is mostly static and rarely changes, otherwise **SSR**. Default when
-unsure: **Next.js SSR**.
+**<SSR | SSG>** — <reason>. Rules: **Ecommerce requires SSR** and **WordPress + WooCommerce requires
+SSR** (carts/checkout need per-request rendering — any SSR framework works; Next.js is the default, not
+a requirement); **WordPress may be SSG (Astro)** when the site is mostly static and rarely changes,
+otherwise **SSR**. Default when unsure: **Next.js SSR**.
 ```
 
 ## Example — WordPress + Ecommerce

package/skills/headless/steps/03-provision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: headless-step-provision
-description: "Step 3 (provision) of the Hostinger Headless flow. Chooses the backend from brief.md (wordpress | ecommerce | webapp), then routes to the matching subfolder to provision it; writes site.json."
+description: "Step 3 (provision) of the Hostinger Headless flow. Chooses the backend from brief.md (wordpress | ecommerce | webapp), then routes to the matching subfolder to provision it; writes site.json. WordPress + WooCommerce routes to the wordpress subfolder with the WooCommerce store turned on — it is not a separate backend."
 ---
 
 # headless-step-provision
@@ -25,19 +25,74 @@ Read the brief's **Suggested backend** section:
 | Suggested backend | Follow |
 |---|---|
 | WordPress | `wordpress/SKILL.md` |
+| WordPress + WooCommerce | `wordpress/SKILL.md` **with the WooCommerce store on** (see below) |
 | Ecommerce | `ecommerce/SKILL.md` |
 | Webapp | `webapp/SKILL.md` |
 
 If the section is missing or names something else, go back to **refine** — don't pick one here.
 Tell the user the backend and its one-line reason before provisioning.
 
-> **Supported backends: `wordpress`, `ecommerce` and `webapp`.** `webapp` is a plain Node.js app host
-> (an empty website — no CMS, no store, no `/cms`) for any app/SPA that brings its own code and data; it
-> never installs WordPress. PocketBase is not available in this version — refine never proposes it, and
-> there is no `pocketbase/` subfolder; if a brief somehow names it, stop and tell the user rather than
-> improvising it. A **WordPress + Ecommerce** brief has no single combined `start-setup` type yet: stop,
-> tell the user it isn't supported as one site, and offer to continue with just WordPress or just
-> Ecommerce — then route to that one subfolder.
+> **WordPress + WooCommerce is the WordPress backend with a store — not a new backend.** Route it to
+> `wordpress/SKILL.md` and follow that recipe's **optional WooCommerce tail** (install + activate the
+> `woocommerce` plugin and verify the store endpoints; the catalog is seeded later through the per-site WP
+> MCP's native `wc-*` abilities — no custom plugin, no consumer key). `site.json → backend` stays
+> `"wordpress"`; the store is recorded under `site.json → woocommerce` (`enabled: true`). Everything else
+> downstream that routes on
+> `wordpress` (content-model push, deploy's `/cms` preservation, done's wp-admin login) then works
+> unchanged.
+
+> **Supported backends: `wordpress` (optionally with a WooCommerce store), `ecommerce` and `webapp`.**
+> `webapp` is a plain Node.js app host (an empty website — no CMS, no store, no `/cms`) for any app/SPA
+> that brings its own code and data; it never installs WordPress. PocketBase is not available in this
+> version — refine never proposes it, and there is no `pocketbase/` subfolder; if a brief somehow names
+> it, stop and tell the user rather than improvising it. A **WordPress + Ecommerce** brief (two separate
+> backends — a WordPress site **and** a Hostinger Ecommerce store) has no single combined `start-setup`
+> type yet: stop, tell the user it isn't supported as one site, and offer either to continue with just
+> WordPress or just Ecommerce (route to that one subfolder), **or**, if they want content and a store on
+> **one** site, to switch the brief to **WordPress + WooCommerce** — the one-site path, which routes to
+> `wordpress/SKILL.md` with the store on.
+
+## Onboarding handoff — swap an existing empty headless shell (do this before creating anything)
+
+Onboarding can create the website **before** you ever run, then paste the build prompt into this agent.
+When it does, the domain already has an **empty headless shell**: a website set up with
+`hosting_websites_start-setup { type: "headless_empty" }` — `website_type` is `headless`, but **nothing
+is installed** (no WordPress at `/cms`, no store). It is the hosting slot only, waiting for a backend.
+
+So provision has **two entry shapes**, and each subfolder's *detect* step picks between them:
+
+- **An empty headless shell already exists for the domain → adopt it and *swap* it to the chosen
+  backend. Never call `start-setup` again, never create a second site.** The swap is backend-specific:
+  - **WordPress** → install WordPress **into the existing shell's `/cms`** with
+    `wordpress_installations_install { type: "headless" }` (it rewrites the root `.htaccess` and marks
+    the site headless-WordPress). Do **not** use `start-setup { type: "headless_wordpress" }` — that is
+    only for creating a fresh site.
+  - **Ecommerce** → the empty headless shell **is** the storefront host already (a `headless_ecommerce`
+    website installs no store engine either). Adopt it as the frontend host and go straight to creating
+    the store + custom sales channel.
+- **No site exists for the domain at all → create it fresh, exactly as each subfolder defines today**
+  (`start-setup` with the backend's own `type`).
+
+> **Webapp is not part of this handoff at all.** `webapp` is **not** reached on the usual onboarding
+> flow — it is only triggered by experimental actions — so it **ignores headless instances entirely**:
+> it never detects, adopts or swaps an empty headless shell, and provisions its own **Node.js app host**
+> exactly as `webapp/SKILL.md` defines today. The swap below is **WordPress and Ecommerce only**.
+
+**How to tell an empty shell from an already-provisioned backend** (both read `website_type: headless`):
+
+1. Exact-match the domain row in `hosting_websites_list` — if there is **no** row, nothing exists → create fresh.
+2. Within 24 h of onboarding, `hosting_websites_list-setups` still shows the setup `type`
+   (`headless_empty` = empty shell; `headless_wordpress` = WordPress already; `headless_ecommerce` = an
+   ecommerce host). Beyond 24 h the setup drops off — fall back to the backend probe:
+3. `wordpress_installations_list { username, domain, ownership: "all" }` — a row with `directory: "cms"`
+   and `is_valid: true` means WordPress is **already** installed (adopt, don't swap); **no** such row on
+   a `headless` site means the shell is still empty and WordPress must be swapped in. A local `site.json`
+   with a recorded backend means a previous run already provisioned — trust reality over it, but it tells
+   you not to expect an empty shell.
+
+This only changes *detect*. Everything after the swap (verify, `site.json`, the WooCommerce tail, the
+background fire/join split) is identical to a fresh provision. A swap that installs WordPress is still
+asynchronous — fire it, record `provision.in_progress`, and join at the barrier just like a fresh create.
 
 ## Step 2 — Fire (don't block)