@hostinger/mcp 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.4.0 — 2026-10-20
+
+### Operations
+
+- Changed the description and input schema of `hosting_deploy`
+
+### Also in this release
+
+- Documentation: `README.md`
+- Dependencies: `package-lock.json`
+- Request handling and authentication: `src/core/runtime.js`, `src/core/runtime.ts`
+- Build and packaging: `types.d.ts`
+
+## 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/README.md

@@ -1816,7 +1816,7 @@ interface in the provided website URL.
 
 #### hosting_deploy
 
-Deploy, publish or upload a website to Hostinger web hosting (Shared, Cloud): static HTML, PHP, a nodejs (Node.js) app, a whole WordPress site, or a WordPress plugin or theme, from a local directory, an archive or a GitHub or GitLab repository. It detects what the project is and does the upload, build and Git setup itself: do not call upload or build operations, and do not archive the directory yourself. WARNING: it overwrites the website's contents and cannot be undone; confirm the domain with the user before deploying to a site that already has content. A Node.js build runs on the server: this returns a buildUuid at once, then call hosting_get-deployment until the build state is completed or failed. Static, PHP, plugin and theme deploys are done when this returns; a WordPress site import only starts, and its files are extracted a few minutes later. From Git, pass type (static or nodejs) unless the site already runs a Node.js app or you pass Node.js settings; a static or PHP site deploys the branch now and again on every push; a Node.js site builds the branch now and on every later push, with the settings stored for the site (when none are stored, pass appType and nodeVersion from the project's engines, plus outputDirectory and buildScript if the app has a build step). Git needs GitHub or GitLab connected once in hPanel.
+Deploy, publish or upload a website to Hostinger web hosting (Shared, Cloud): static HTML, PHP, a nodejs (Node.js) app, a whole WordPress site, or a WordPress plugin or theme, from a local directory, an archive or a GitHub or GitLab repository. It detects what the project is and does the upload, build and Git setup itself: do not call upload or build operations, and do not archive the directory yourself. WARNING: it overwrites the website's contents and cannot be undone; confirm the domain with the user before deploying to a site that already has content. A Node.js build runs on the server: this returns a buildUuid at once, then call hosting_get-deployment until the build state is completed or failed. For a plugin or theme on a headless WordPress (installed in the cms folder), pass headless: true. Static, PHP, plugin and theme deploys are done when this returns; a WordPress site import only starts, and its files are extracted a few minutes later. From Git, pass type (static or nodejs) unless the site already runs a Node.js app or you pass Node.js settings; a static or PHP site deploys the branch now and again on every push; a Node.js site builds the branch now and on every later push, with the settings stored for the site (when none are stored, pass appType and nodeVersion from the project's engines, plus outputDirectory and buildScript if the app has a build step). Git needs GitHub or GitLab connected once in hPanel.
 
 - **Method**: `custom`
 - **Path**: `custom`

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "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.4.0",
   "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.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@hostinger/mcp",
-      "version": "3.3.0",
+      "version": "3.4.0",
       "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