@hostinger/mcp 3.2.2 → 3.3.0

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

@@ -0,0 +1,193 @@
+---
+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/ai/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.
+
+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) | site exists | **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 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):
+
+- **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,206 @@
+---
+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."
+---
+
+# 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.
+
+**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:
+
+- 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.
+- 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.
+
+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."*
+
+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
+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.
+
+## Step 4 — Recommend the backend
+
+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. |
+| **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.
+- **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 → 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
+
+Send **one** message that carries both the recommendation and the brief summary:
+
+- **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
+  (*"assumed: warm, minimal look"*) so the user sees what they skipped.
+
+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.
+
+## 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**` or
+`**Webapp**`, followed by an em dash and the one-line reason.
+
+## `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 | Webapp>** — <one-line reason>.
+<"Confirmed by the user." or "User chose this over the recommended <X> because <reason>.">
+
+## 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**.
+```
+
+## 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,62 @@
+---
+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."
+---
+
+# 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` |
+| 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.
+
+## 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.

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

@@ -0,0 +1,133 @@
+---
+name: headless-step-provision-ecommerce
+description: "Provision a Hostinger Ecommerce backend for the Hostinger Headless flow: ensure the hostinger-ecommerce MCP is connected, create the headless website (frontend host) and a Hostinger Ecommerce STORE with a custom (headless) sales channel, set shipping + payment, and record it all in site.json."
+---
+
+# headless-step-provision-ecommerce
+
+Provision a **Hostinger Ecommerce** backend for `<domain>` and prove it is ready. Two distinct things:
+
+1. A **headless website** (`type: "headless_ecommerce"`) — this is only the **hosting slot for the
+   storefront you'll build**. It installs **no store engine** (no `/cms`, no API on the domain).
+2. A **Hostinger Ecommerce store** — a separate object created through the **Ecommerce API**, with a
+   **custom (headless) sales channel**. The storefront reads this store's **public Storefront Core V2
+   API**, keyed on the sales channel. This is the real backend.
+
+**Out:** `site.json` (store id, custom sales channel id, URLs).
+
+> ## ⚠️ Prerequisite: the `hostinger-ecommerce` MCP server must be connected
+> Store management is **not** in the `hosting`/`wordpress` MCP groups — it's the separate
+> **`hostinger-ecommerce`** group (`ecommerce_*` ops, OAuth-backed, no API token needed). If those
+> tools aren't available, add the server and **reconnect the session** before continuing:
+> ```bash
+> claude mcp add-json hostinger-ecommerce '{"command":"npx","args":["--package=@hostinger/mcp@latest","hostinger-ecommerce-mcp"],"env":{"USER_AGENT":"extension;claude-code;via-cursor;1.4.2"}}' --scope user
+> ```
+> (For other tools, enable the **Ecommerce** MCP in the Hostinger Connector.) A newly added MCP server
+> only loads on a session restart/reconnect.
+>
+> **Can't restart your own session? Don't block — drive the server directly.** A coding agent usually
+> can't reconnect itself, so instead of stopping, run the stdio server yourself and speak MCP to it:
+> spawn `npx --package=@hostinger/mcp@latest hostinger-ecommerce-mcp` (same `USER_AGENT` as above) and
+> send newline-delimited JSON-RPC over its stdin/stdout — `initialize` → the `notifications/initialized`
+> notification → `tools/list` → `tools/call`, where the tools are `search` / `execute` / `multi-execute`
+> (call ops exactly as in-session: `{ "name": "execute", "arguments": { "operation": "…", "params": {…} } }`).
+> It self-authenticates with the same stored Hostinger OAuth creds as the other connected servers, so
+> there is **no token to handle** (keep any secret off the command line). Your sandbox may ask the user
+> to approve spawning it — ask once, then proceed. Only fall back to asking the user to restart if
+> driving the server directly isn't permitted.
+>
+> Verify the tools work (in-session or via the direct drive) with a search — e.g. "list stores" →
+> `ecommerce_stores_list` — before proceeding.
+> The authoritative, always-current build guide is `ecommerce_miscellaneous_custom-storefront-setup-instructions` — read it once per build.
+
+All website-lifecycle calls go through the `hosting` connector (`execute`); all store calls through the
+`hostinger-ecommerce` MCP.
+
+## Step 1 — The headless website (frontend host)
+
+Same lifecycle as `../wordpress/SKILL.md` Steps 1–2, but `type: "headless_ecommerce"`:
+
+1. Detect: `hosting_websites_list` / `hosting_websites_list-setups` (exact-match the domain). `completed`
+   → adopt. `running` → poll. `failed` → stop, point at hPanel.
+2. Create (only if absent): `hosting_websites_start-setup { order_id, type: "headless_ecommerce", domain }`
+   — **omit `domain`** for a temporary subdomain: the setup generates one itself (don't call a separate
+   subdomain op first — passing a generated free subdomain back as `domain` 422s). The response carries
+   the generated domain; if it differs from the workspace dir, move `~/.hostinger/<old>/` → `<new>/` and
+   update `brief.md`. Poll `list-setups` to `completed`. `website_type` will be `headless`.
+
+> Don't expect `/cms` or any API on this domain — it serves the storefront you build (Step 6) and
+> deploy (Step 8).
+
+## Step 2 — Resolve or create the store + custom sales channel
+
+`ecommerce_stores_list` → reuse an existing store if this build already made one; otherwise create:
+
+```json
+{ "operation": "ecommerce_stores_create",
+  "params": { "name": "<store name>", "country_code": "US", "company_email": "<email>",
+    "company_name": "<store name>", "language": "en",
+    "sales_channel": { "type": "custom", "external_id": "<slug>-headless" } } }
+```
+
+This returns `store.id` (`store_*`) **and** a custom `sales_channel.id` (`scha_*`) in one call — the
+custom channel is what the headless storefront is keyed on. (You can also add one later with
+`ecommerce_sales-channels_create { store_id, type:"custom", name }`.) Currency comes from
+`country_code` (`default_currency_code`); all prices are **minor units** (cents).
+
+## Step 3 — Store readiness: shipping + payment
+
+A store needs ≥1 shipping zone and ≥1 payment method to check out.
+
+- **Shipping:** `ecommerce_shipping_set-store { store_id, price }` (minor units; 0 = free).
+- **Payment:** `ecommerce_payments_enable-manual-method { store_id, title }`.
+
+> **Known gate — free accounts have no payment method, and therefore no checkout.** On a **free
+> account** (and any account/store without a paid Hostinger Ecommerce plan), `enable-manual-method`
+> returns **HTTP 402**, and checkout later fails with `400 payment_provider_not_configured`. This is
+> **expected, not an error** — payment, and therefore checkout, is simply unavailable on the plan. The
+> catalog and the storefront still work fully. **Never block, stop, loop or retry the build on this:**
+> - Record `payment_enabled: false` in `site.json` (set `shipping_enabled` as usual).
+> - Tell the user in one line that checkout needs a paid Ecommerce plan, and carry straight on.
+> - Treat the 402 as a normal outcome — don't surface it as a failure or re-attempt the call.
+> - Never ask the user for payment credentials.
+>
+> Every downstream stage reads `site.json → ecommerce.payment_enabled` and, when it is `false`, skips
+> all checkout wiring and verification (see content-model Step 5, frontend, deploy). A store with
+> `payment_enabled: false` is a **complete, valid build** — a browsable catalog without checkout.
+
+## Step 4 — Verify
+
+- `ecommerce_stores_metadata { store_id }` → `has_shipping` true; `has_payment_methods` (may be false,
+  see the gate); read `default_currency` (`decimal_digits`, `template`) here, don't guess.
+- Public Storefront V2 answers for the channel (no auth):
+  `GET https://api-ecommerce.hostinger.com/v2/channels/<scha_*>/products?limit=100` → 200 (empty until
+  content-model seeds products — fine here).
+- `GET https://<domain>/` returns the Hostinger default page until the storefront is deployed — expected.
+
+## Step 5 — Record `site.json`
+
+```json
+{
+  "backend": "ecommerce",
+  "website_type": "headless",
+  "order_id": 1007223428,
+  "username": "u…",
+  "ecommerce": {
+    "store_id": "store_…",
+    "sales_channel": { "id": "scha_…", "type": "custom", "external_id": "…-headless" },
+    "currency": "usd",
+    "payment_enabled": false,
+    "shipping_enabled": true
+  },
+  "urls": {
+    "site": "https://<domain>",
+    "storefront_api": "https://api-ecommerce.hostinger.com/v2/channels/<scha_*>",
+    "store_admin": "https://ecommerce.hostinger.com/store/<store_*>"
+  },
+  "provisioned_at": "…",
+  "verified_at": "…"
+}
+```
+
+No secrets in `site.json`. After deploy, link the channel to the live domain with
+`ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (done in the deploy stage).