@hostinger/mcp 3.2.2 → 3.3.1

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

@@ -0,0 +1,209 @@
+---
+name: headless-step-check-state
+description: "First build step of the Hostinger Headless flow, run right after connect. Works out where a given domain's build stands — is a run already in progress, does the site already exist, how far did it get — by reconciling the global workspace state under ~/.hostinger/<domain>/ with what the Hostinger connector reports, then guides the user to continue, switch or buy a domain, or start over. Owns all resume/position logic for the flow."
+---
+
+# headless-step-check-state
+
+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.
+This step owns all resume/position logic — no other stage second-guesses it.
+
+Nothing in this step creates, provisions, deploys, or deletes anything. It reads and guides.
+
+---
+
+## Where state lives
+
+Everything for a domain lives under the global site workspace **`~/.hostinger/<domain>/`** — one
+directory per domain, under the user's home (`~` = `$HOME`), **not** the current working directory.
+The directory name **is** the domain, so `state.json` inside does not store it. Because it's global,
+`~/.hostinger/` holds every site the user has built and each one is discoverable and resumable from
+any directory — no collisions.
+
+`state.json` shape (`stage` is the *next* stage to run; `provision` is the background task's status,
+present only once provision has fired):
+
+```json
+{ "tool": "claude-code", "stage": "content_model",
+  "provision": { "status": "in_progress", "domain": "<domain>", "started_at": "…" },
+  "updated_at": "…" }
+```
+
+`provision.status` is `in_progress` or `completed` — but it is a **hint**: always re-verify it against
+`hosting_websites_list-setups` (Step 1) before trusting it to gate an instance-barrier step.
+
+---
+
+## Step 0 — Start the run log
+
+Before anything else, start a run and the stage (see *Run log and build report* in the top-level
+`SKILL.md`):
+
+```bash
+node <skill>/run-log.mjs <domain> run-start --tool <tool> --model <model> --skill <skill version>
+node <skill>/run-log.mjs <domain> stage-start check_state
+```
+
+If an earlier run on this domain never wrote its report, `run-start` closes it as `abandoned` first.
+
+Then send any build reports that haven't reached Hostinger yet (that abandoned run, or a send that
+failed last time):
+
+```bash
+node <skill>/run-log.mjs <domain> unsent
+```
+
+Each line is `<run> <path>`. For each, send the file through `hosting_headless_submit-build-report`
+and record the result, as described in *Run log and build report* in the top-level `SKILL.md`. One
+try each. Don't ask first; if any went out, say so in one line (e.g. "Sent 1 earlier build report to
+Hostinger."). Don't let a failure hold up this step.
+Check-state runs once per session. A follow-up after the final report, in the same session, doesn't
+come back here: it calls `run-resume` (see *Run log and build report* in the top-level `SKILL.md`).
+
+## Step 1 — Is a build actively running right now? (check this before anything else)
+
+Keep two things separate, and **never guess from a timestamp.**
+
+- **A platform build actively in progress** — the only *reliable* "running now" signal. Check
+  `hosting_websites_list-setups { "domain": "<domain>" }` and exact-match the domain row:
+  - `status: running` → provisioning is underway **right now** (a background provision from an earlier
+    turn). Don't start a second one — reconcile `state.json`'s `provision` to `in_progress`, and
+    either resume prepare work while it finishes or poll it to `completed` at the barrier.
+  - `status: failed` → not running; route to provision to self-heal (Step 3).
+  - `completed` → provision is done; set `provision.status` to `completed`. Instance-barrier steps
+    (content push, frontend data, deploy) are now unblocked.
+  - no row → not provisioned yet; carry on.
+
+  This check **is** the source of truth for `provision.status`: a stored `in_progress`/`completed` in
+  `state.json` is only a hint until this reconciles it.
+
+- **A `.lock`** — `~/.hostinger/<domain>/.lock`. It only tells you *a previous run
+  touched this domain*. **Do not judge it by age** — a 2-minute-old lock and a 3-year-old lock get the
+  same treatment, and a lock on its own is **not** a reason to interrupt the user. Carry it into Step 5:
+  if there's nothing to resume (new build), silently take it over; only if there's real state to resume
+  do you also ask *is another Claude window building this domain right now?* (yes → stop; no → take
+  over).
+
+Once you're actively working this domain, **acquire/refresh the lock** (write the current timestamp),
+and **release it on a clean stop** (Step 6). The lock marks an active session, nothing more.
+
+---
+
+## Step 2 — Read the workspace directory
+
+Look at `~/.hostinger/<domain>/`:
+
+- **Absent** → no history for this domain in the workspace.
+- **Present** → read `state.json` (its `stage`) and whatever artifacts exist (`brief.md`,
+  `site.json`, …). Treat these as a hint, not the truth.
+
+---
+
+## Step 3 — Verify against reality (reality wins)
+
+Query the Hostinger connector — the local files are never trusted on their own:
+
+- **Does the site exist?** `hosting_websites_list { "domain": "<domain>" }`. ⚠️ This filter is a
+  **case-insensitive substring match**, not exact — so `test.com` would also return
+  `shop.test.com`. **Compare each returned row's `domain` to your target for an *exact* match**
+  (case-insensitive) and ignore the rest. No exact row ⇒ the domain is free. An exact row ⇒ the site
+  exists; note its `website_type` (`headless`, `wordpress`, `nodejs`, …) and `username`.
+- **How far did it get?** If the site exists, check its setup via
+  `hosting_websites_list-setups { "domain": "<domain>" }` (exact-match the row the same way):
+  - `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.
+
+---
+
+## Step 4 — Determine the position
+
+Connect always writes `state.json` (with `stage: check_state`) before this step runs, so local
+state is never truly empty. **"Local state: none" here means only connect artifacts exist** —
+`connect.json` + a `state.json` still pointing at `check_state`/`refine`, and **no build artifacts
+yet** (`brief.md`, `site.json`, …).
+
+| Local state | Reality (domain) | Position |
+|---|---|---|
+| none (connect only) | free | **new build** — start from refine |
+| 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 |
+
+---
+
+## Step 5 — Guide the user
+
+The question to ask depends on whether there is actually **something to resume** — i.e. **build
+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 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.)
+- **Start over / redo a step** — only safe **before anything is provisioned**. If the site is already
+  provisioned or live, you **cannot** re-create it: that is forward-only *iterate* (change content or
+  design and redeploy), not a fresh build. Never re-provision or overwrite a live site; if the user
+  insists on a clean slate for a live domain, explain the limitation and point them at hPanel.
+- **Switch domain** — they want a different domain. A new domain is a **new workspace**
+  (`~/.hostinger/<other-domain>/`, with its own `src/`). Hand off to start that domain's run.
+- **Buy a domain** — they want a custom domain instead of the temporary one. Route to the domain
+  purchase / `connect-domain` flow, then continue with the chosen domain.
+
+When the intent is ambiguous, **ask** — don't guess.
+
+---
+
+## Step 6 — Record and route
+
+Write `~/.hostinger/<domain>/state.json` with the agreed next `stage` and a fresh timestamp. If the
+route isn't a new build, record it with `run-log.mjs <domain> run-update --kind resume` (or
+`redesign` / `iterate`), then end the stage with `stage-end check_state ok --note "<the route>"`.
+Then:
+
+- **Handing straight to the next stage in this same session?** Keep the `.lock` (you are still
+  actively running) and continue.
+- **Stopping and returning control to the user?** (e.g. the next stage isn't built yet, or you are
+  waiting on them.) **Delete the `.lock`** — the session is no longer active, and a leftover lock just
+  forces an unnecessary "is another window running?" question on the next run. Always release the lock
+  on a clean stop; it exists only to mark an actively-running session. A stop is still the end of a
+  run: give the final report and save the build report (`09-done`).
+
+---
+
+## Invariants
+
+- **One directory per domain.** The domain is the key; state files never repeat it.
+- **Never create a second site** on a domain that already has one.
+- **Never re-provision or overwrite a live site.** Recovery is forward-only.
+- **Reality beats local state**, always.
+- **When ambiguous, ask.**

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

@@ -0,0 +1,273 @@
+---
+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), 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
+
+Find out what the user wants to build, guess which backend fits, and write it down. This is a
+**conversation, not a form**: the pasted prompt names a domain and nothing else, so everything about
+the site comes from talking to the user.
+
+**Keep it short.** The only thing you must know is *what they are building* — enough to guess the
+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`.
+
+Nothing in this step touches Hostinger. It only asks, decides and writes.
+
+---
+
+## Step 1 — Read the workspace, then the resume check
+
+Read everything already in `~/.hostinger/<domain>/` (`state.json`, `connect.json`, any notes, images
+or files the user dropped there) — it all counts as input.
+
+If `brief.md` already exists for this domain, **don't overwrite it**. Show the user a three-line
+summary (what the site is, its pages, the suggested backend) and ask: *keep it, or change something?*
+Keep → go to Step 6. Change → edit only what they asked for, then re-confirm (Step 5).
+
+If the site is already provisioned (`site.json` exists), the backend is **fixed** — never change the
+Suggested backend on a provisioned site. Explain that switching backends means a new domain.
+
+## Step 2 — Gather what you already have
+
+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 (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 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."*
+
+> **"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
+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*.
+
+**Round 1 — what it is (the only required round):**
+
+1. **What are you building?** The business or project, and what the site is for.
+2. **Will you sell anything on it?** Physical products, digital products, services with checkout —
+   or nothing. *This decides the backend.* Skip it only when the answer is already unmistakable
+   ("an online shop for my candles", "my personal blog"); when in doubt, ask.
+3. **Who is it for?** The audience, and how they'll find the site. *(skippable)*
+
+**Round 2 — what goes on it (optional, adapt to Round 1):**
+
+- **Content they'll publish over time** — blog posts, articles, news, recipes, portfolio pieces,
+  case studies? How often? Or is it a handful of pages that rarely change?
+- **Pages** — propose a page list from what you know and ask them to add or remove.
+- If they sell: **what and how many** — a rough product count, categories, whether products have
+  variants (size, colour), and the shipping regions.
+
+**Round 3 — how it should feel (optional, skip what you already know):**
+
+This is the round that captures **all design input** — the design step reads it from `brief.md` to derive
+the design directions, so it is **not** asked again later; gather it here:
+
+- **Reference & look** — a **site they like (URL)** and what to take from it, plus a few adjectives for
+  the vibe. Screenshots welcome.
+- **Colours & brand** — brand/accent colours, logo, fonts, existing copy, photos. Note where they live.
+- **Must-haves and no-gos** — contact form, newsletter, bookings, languages, things to avoid.
+
+If the user asks for something outside the scope (user accounts, member areas, bookings with a
+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.
+
+### 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.
+
+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, 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:
+
+- **Is it an app, or a site?** A custom application the user builds/brings (its own logic, its own data,
+  maybe a database) → **Webapp**. A content site or a shop → one of the three above. When the user says
+  "my app / SPA / dashboard / tool", or hands you an existing app project to deploy, that's **Webapp**.
+- **Selling decides first (for sites).** No selling → WordPress. Selling → Ecommerce or
+  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
+  contact page.
+- **Webapp never uses WordPress or a store.** If the user wants a custom app *and* a CMS/shop, that's two
+  different sites — build the app as a Webapp and tell them the content/commerce backend is a separate
+  domain.
+
+**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 + 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 the plan in one message
+
+Send **one** message that confirms **what you'll build** — the plan, not the plumbing. Lead with the
+site, not the backend:
+
+- **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 the user
+*volunteers* a different backend, use theirs and note it in the brief.
+
+## Step 6 — Write `brief.md` and hand off
+
+Write `brief.md` from the template below. Fill every section from the conversation, defaulting what
+the user skipped and tagging it `(assumed)`; leave out **Products** when nothing is sold. Use the
+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**`,
+`**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
+
+```markdown
+# Brief — <domain>
+
+> Brief agreed with the user on <today>.
+
+## Purpose
+<what the site is, who runs it, what it's for — 2–3 sentences>
+
+## Audience
+<who visits, how they arrive, what device they mostly use>
+
+## Tone
+<voice in a sentence or two>
+
+## Design direction
+<look & feel in a few adjectives; **reference site(s)** the user named (URLs) and what to take from them
+(layout, structure, mood); colours / brand palette; any screenshots. This is where ALL design questions
+land — the frontend step reads this and does not re-ask. Write "Agent's choice: <short style>" when the
+user didn't specify.>
+
+## Pages
+- **<Page>** — <one-line purpose>
+- …
+
+## Products
+<only when selling: what is sold, rough count, categories, variants, shipping regions, payments>
+
+## Content
+<what the owner will publish over time and how often — or "A few fixed pages; no ongoing content.">
+
+## Must-haves
+- …
+
+## Out of scope
+- …
+
+## Assets
+<logo, colours, photos, copy the user provided and where they are; "None yet" if none>
+
+## Suggested backend
+**<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** 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
+
+> A ceramicist sells around 30 handmade pieces and writes a monthly studio journal.
+
+```markdown
+## Suggested backend
+**WordPress + Ecommerce** — sells ~30 products with checkout, and the owner publishes a monthly
+studio journal they want to edit themselves.
+Confirmed by the user.
+```

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

@@ -0,0 +1,117 @@
+---
+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. WordPress + WooCommerce routes to the wordpress subfolder with the WooCommerce store turned on — it is not a separate backend."
+---
+
+# headless-step-provision
+
+Router. The backend is decided in **refine** and recorded in `brief.md`; this step only routes to the
+matching subfolder, which provisions it.
+
+**In:** `brief.md`. **Out:** `site.json` (written by the subfolder).
+
+**This stage runs in the background.** Provisioning is mostly a poll wait, so it splits in two: a
+**fire** half (detect + create, returns straight away) and a **join** half (poll to `completed`,
+verify, write `site.json`). Fire it, record `provision.in_progress`, then go do the prepare work of
+the other stages (content-model prepare, frontend shell) while it settles. Only cross back to
+the join half when an instance-barrier step needs the live backend. See *Background provision & the
+instance barrier* in the top-level `SKILL.md`. An agent that can't interleave simply does fire and
+join back-to-back — still correct, just no overlap.
+
+## Step 1 — Route on the suggested backend
+
+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.
+
+> **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)
+
+Follow the chosen subfolder's `SKILL.md` through **detect + create** (its "start-setup" call). The
+moment the create is accepted and queued, record it in `state.json` and **return** — do not sit on the
+readiness poll:
+
+```json
+{ "stage": "content_model",
+  "provision": { "status": "in_progress", "domain": "<domain>", "started_at": "<now>" } }
+```
+
+Now go run the prepare work that doesn't need the backend (content-model prepare, frontend
+shell). The subfolder's readiness poll, verification and `site.json` are the **join** half below.
+
+## Step 3 — Join (at the instance barrier)
+
+When an instance-barrier step is about to run (content-model push, frontend data wiring, deploy) — or
+right away, if the agent can't interleave — finish the subfolder's `SKILL.md`: **poll to `completed`**,
+run its verification, and write `site.json` (which records the chosen `backend`). Then set
+`provision.status` to `"completed"` in `state.json` with a fresh `updated_at`. On resume, treat a
+stored `in_progress` as a hint only — re-poll `hosting_websites_list-setups` for the truth first.