@hostinger/mcp 3.2.1 → 3.3.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ Generated at release time from the diff between the previous and current
 build. Tool changes are listed individually; everything else is summarised
 by area.
 
+## v3.3.0 — 2026-10-19
+
+### Also in this release
+
+- Bundled agent skills: 33 files
+- Other files: `src/core/skills.js`, `src/core/skills.ts`
+
+## v3.2.2 — 2026-10-19
+
+### Operations
+
+- Added `hosting_cdn_disable` — Disable CDN
+- Added `hosting_cdn_enable` — Enable CDN
+- Added `hosting_cdn_purge-cache` — Purge CDN cache
+- Added `hosting_cdn_status` — Get CDN status
+- Changed the description of `hosting_cache_clear-website`
+
+### Also in this release
+
+- Documentation: `README.md`
+- Request handling and authentication: `src/core/runtime.js`, `src/core/runtime.ts`
+- Build and packaging: `types.d.ts`
+
 ## v3.2.1 — 2026-10-19
 
 ### Operations

package/README.md

@@ -69,7 +69,7 @@ pnpm update -g @hostinger/mcp
 
 This package installs the following MCP server commands:
 
-- `hostinger-api-mcp` — unified server over every operation (399 total)
+- `hostinger-api-mcp` — unified server over every operation (403 total)
 - `hostinger-agency-hosting-mcp` — 42 operations for agency-hosting
 - `hostinger-agent-readiness-mcp` — 3 operations for agent-readiness
 - `hostinger-billing-mcp` — 9 operations for billing
@@ -77,7 +77,7 @@ This package installs the following MCP server commands:
 - `hostinger-domains-mcp` — 42 operations for domains
 - `hostinger-ecommerce-mcp` — 29 operations for ecommerce
 - `hostinger-horizons-mcp` — 6 operations for horizons
-- `hostinger-hosting-mcp` — 62 operations for hosting
+- `hostinger-hosting-mcp` — 66 operations for hosting
 - `hostinger-mail-mcp` — 38 operations for mail
 - `hostinger-reach-mcp` — 56 operations for reach
 - `hostinger-vps-mcp` — 67 operations for vps
@@ -1833,7 +1833,8 @@ Check deployment status, build status, build logs and why a build failed (failur
 Permanently clears all server-side cache for the website at once. Use it when content was
 updated and needs to be visible immediately, or after making major changes.
 
-Also purges the Hostinger CDN cache when CDN is enabled on the website. For a WordPress
+Also purges the Hostinger CDN cache when CDN is enabled on the website. To purge only the CDN
+cache and leave the server cache untouched, use `Purge CDN cache`. For a WordPress
 installation living in a subdirectory, pass the directory query parameter to clear its cache.
 
 - **Method**: `DELETE`
@@ -1861,6 +1862,61 @@ Does nothing if caching is already in the requested state.
 - **Method**: `PATCH`
 - **Path**: `/api/hosting/v1/accounts/{username}/websites/{domain}/cache/toggle`
 
+#### hosting_cdn_disable
+
+Turns off the Hostinger CDN for the website domain. Once DNS propagation completes, the
+website content is served directly from the origin server. Repeating the call is safe; when
+CDN is already disabled, it applies the DNS change again.
+
+Returns 422 for platform-managed domains (for example `*.hostingersite.com` and
+`*.app-preview.com`), where CDN cannot be disabled, even when CDN is already off. Also returns
+422 while the account is being moved to another server (retry after the move finishes), or
+when the CDN provider rejects the change. Returns 404 when the domain is not a website on the
+account.
+
+- **Method**: `POST`
+- **Path**: `/api/hosting/v1/accounts/{username}/websites/{domain}/cdn/disable`
+
+#### hosting_cdn_enable
+
+Turns on the Hostinger CDN for the website domain, which speeds up page loads and reduces the
+load on the server. Works for the main domain, parked domains and subdomains of the account.
+
+Enabling changes the domain's DNS records and usually takes a few seconds. After that, DNS
+propagation can take a few more minutes before visitors are served through the CDN.
+
+Repeating the call is safe, for example after a timeout. When CDN is already enabled, it
+applies the DNS change again and refreshes the CDN SSL certificate.
+
+Returns 422 when the account is disabled, while the account is being moved to another
+server (retry after the move finishes), or when the CDN provider rejects the change.
+Returns 404 when the domain is not a website on the account.
+
+- **Method**: `POST`
+- **Path**: `/api/hosting/v1/accounts/{username}/websites/{domain}/cdn/enable`
+
+#### hosting_cdn_purge-cache
+
+Purges the website's content from the Hostinger CDN edge cache only. The origin server cache
+is not touched; to clear both, use `Clear website cache`.
+
+Returns 422 when CDN is not enabled on the website. Returns 404 when the domain is not a
+website on the account.
+
+- **Method**: `DELETE`
+- **Path**: `/api/hosting/v1/accounts/{username}/websites/{domain}/cdn/purge`
+
+#### hosting_cdn_status
+
+Returns whether the Hostinger CDN is enabled for the website domain. Works for the main
+domain, parked domains and subdomains of the account.
+
+The domain must be the exact website name as listed on the account, without a `www.` prefix.
+Returns 404 when the domain is not a website on the account.
+
+- **Method**: `GET`
+- **Path**: `/api/hosting/v1/accounts/{username}/websites/{domain}/cdn/status`
+
 #### hosting_cron-jobs_list
 
 Returns the list of cron jobs configured for the specified account, including their schedule and command.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "3.2.1",
+  "version": "3.3.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.2.1",
+  "version": "3.3.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.2.1",
+  "version": "3.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@hostinger/mcp",
-      "version": "3.2.1",
+      "version": "3.3.0",
       "transport": {
         "type": "stdio"
       },

package/skills/headless/SKILL.md

@@ -1,56 +1,267 @@
 ---
 name: hostinger-headless
-description: "Build, connect, or iterate on a website hosted on Hostinger — provision hosting and a domain, optionally seed an ecommerce store with a real hosted checkout or a WordPress content backend (headless CMS/blog), build the frontend, deploy, and verify. Requires an authenticated Hostinger MCP session (see entry/skill.md). Triggers: build me a site on Hostinger, deploy this to Hostinger, connect this project to Hostinger, add a store to my Hostinger site, add a blog to my Hostinger site, update my Hostinger site."
+description: "Orchestrator for the Hostinger Headless build flow — build and deploy a real website on the user's Hostinger account from a single prompt that names a domain. Holds the stage flow and the state contract, and drives each stage in sequence: connect, check state, refine, provision, content model, design, frontend, validate, deploy, done. Triggers: build a headless site for <domain>, build me a site, create a website, make me a website, deploy this to Hostinger, host this on Hostinger, connect this project to Hostinger."
 ---
 
-# Hostinger Headless
+# Hostinger Headless — build a website with your own AI tool
 
-This skill turns a prompt into a live website on Hostinger. Its job is to own the full run: check the account, provision hosting and a domain, seed the backend (an ecommerce store when the intent calls for selling), build the frontend, deploy it, and verify the result.
+## Context
 
-The frontend is built ad-hoc to the user's intent — there is no template library. The backend pieces are real Hostinger products: web hosting (static or Node.js), domains and DNS, Hostinger Ecommerce with its public Storefront API and hosted checkout, and WordPress as a headless CMS/blog backend read through the public WP REST API.
+You are an AI coding agent. The user pasted a short prompt that points you here — something like:
 
-## Preconditions
+> Build a Headless site for `example.com` using hostinger.com/ai/skill.md
 
-1. An authenticated Hostinger MCP session — the entry skill's bootstrap handled this. If MCP tools fail with auth errors, send the user back through `entry/skill.md`.
-2. The Hostinger MCP operations for **hosting** (plus **ecommerce** when the run involves a store, and **wordpress** when it involves a content backend). Operation availability varies per user — product groups can be toggled in the Hostinger Connector. When search cannot find a needed operation, ask the user to enable that product group (or configure the scoped binary, e.g. `hostinger-hosting-mcp`) rather than improvising around it.
-3. An active hosting plan (checked in Setup §1). Hostinger hosting is a paid product: if the account has no usable plan, inform the user plainly that a subscription is required, link them to https://www.hostinger.com/web-hosting, and pause until they confirm the purchase. Do not treat this as an error — it is a normal step for new accounts. Everything that doesn't need hosting (planning, building the frontend locally) can proceed while they decide.
+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.
 
-## Resolving the operation
+This file is the **orchestrator**. It is public and stable: it never changes and never moves. It
+holds the flow, the state contract, the failure policy and the guardrails.
 
-Resolve by intent first, disk second — never let an empty directory override what the user is asking for. Check `iterate` first (it's decided by an unambiguous on-disk signal):
+### The domain parameter
 
-- `iterate` — a `.hostinger/site.json` is present in the project: the site is already deployed through this skill and the user wants changes. Reuse the recorded domain/site details; apply only the delta the new intent needs (edit frontend → redeploy; add a store → run `references/STORE.md` then redeploy). Never re-provision an existing site.
-- `connect` — a frontend project already on disk (or brought in as a zip/export/URL) that is not yet on Hostinger, with language like "deploy this / host this on Hostinger / connect this project". Emptiness of the CWD at trigger time is not a create signal when a design is brought in from elsewhere.
-- `create` — a new site from a prompt with nothing brought in: "build me a store / portfolio / site…".
+The pasted prompt contains exactly two things that matter:
 
-If signals conflict, ask the user — don't guess.
+- **This URL** — `hostinger.com/ai/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.
 
-## The run
+The prompt does **not** say what kind of site to build. Do not assume or invent it. Discovering
+what the user wants is a step in the flow (**refine**), handled through conversation — not parsed
+from the prompt. If no domain is present, stop and ask for it before doing anything else.
 
-1. **Discovery** — from the prompt (and the project on disk for connect/iterate), infer: does this run need a store (any buy/sell/product intent → yes)? Does it need owner-managed content — a blog, news, or anything the owner edits without a redeploy (→ WordPress backend; static copy that rarely changes does not qualify)? What brand, copy, and structure does the site need? What stack fits — plain static HTML/CSS/JS for simple sites (default), a static-output framework build, or a Node.js app when SSR or server code is genuinely required? Prefer static: it deploys fastest and has no build-failure surface. Ask the user only what you cannot infer.
-2. **Setup** (`references/SETUP.md`) — plan check, then provision the website on a free subdomain (or the user's own domain) and wait until it's ready.
-3. **Store** (`references/STORE.md`, only when commerce is needed) — resolve or create the store and its `custom` sales channel, seed products/shipping/payment, and note the `sales_channel_id` for the frontend.
-4. **Content backend** (`references/WORDPRESS.md`, only when owner-managed content is needed) — install WordPress on a dedicated subdomain, wait until it's ready, and hand the owner a wp-admin login link. The frontend reads it through the public WP REST API.
-5. **Build** — create or wire the frontend. For store runs, follow the frontend contract in `references/STORE.md` (catalog fetched at runtime from the public Storefront API, cart in `localStorage`, client-side checkout — never embed an API token in the site). For content runs, follow the frontend contract in `references/WORDPRESS.md` (posts fetched at runtime from the WP REST API, rendered HTML bodies, graceful empty states). When the app needs MySQL, follow `references/DATABASE.md` (which host each runtime connects to, credentials via env vars or a server-side config file, never in the frontend).
-6. **Deploy** (`references/DEPLOYMENT.md`) — archive and deploy via the matching hosting operation, polling build logs for Node.js runs.
-7. **Verify** — curl the live URL for a 200 and a piece of real page copy; for store runs, confirm a checkout POST returns a redirect URL; for content runs, confirm the WP REST API returns 200 and the frontend renders posts. Show the user the live URL and where to manage things (hPanel: https://hpanel.hostinger.com, the store dashboard for commerce, wp-admin for content).
-8. **Record** — write `.hostinger/site.json` into the project: `{ "domain", "username", "type": "static"|"nodejs", "sales_channel_id"?, "store_id"?, "cms_domain"? }`. This is what makes future runs resolve as `iterate`.
+Nothing in the pasted prompt is ever used for authorization. Authorization comes from the
+Hostinger connector's OAuth token. **This recipe is not a security boundary.**
 
-Run non-interactively wherever possible. The exceptions that must involve the user: the paid-plan confirmation, anything that costs money (a domain purchase, a new subscription), and picking between genuinely equal options the prompt doesn't decide.
+---
+
+## 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.
+
+**The 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`.
+
+**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
+ran), the links, where state lives, and any gaps. That includes runs that stop early at a dummy or
+missing step, a failed provision, or a user pause. Every run also saves a **build report**
+(`run-log.mjs report`, see *Run log and build report* below), on those early stops too.
+
+**Log the run as you go.** Wrap every stage (and each phase of a split stage) in
+`run-log.mjs stage-start` / `stage-end`, and log an event the moment something goes wrong, the user
+corrects you, or a skill is missing or wrong — before you continue. See *Run log and build report*.
+
+**Why this order.** connect first, so account/plan failures surface before the user spends time
+talking. Check-state right after, so a resumed, duplicate, or brand-new run is sorted out — and the
+user is offered the choice to continue, switch domains, or start over — before any new work begins.
+Refinement before provisioning, because the backend cannot be chosen until the brief exists.
+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
+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.
+
+---
+
+## State and artifacts
+
+Everything for a domain — its state **and** its generated source — lives under the **site workspace
+`~/.hostinger/<domain>/`** (resolve `~` to the home directory: `$HOME` in a shell, `os.homedir()` in
+Node — `~/.hostinger` means `$HOME/.hostinger`). This is a **global, per-user** location, not a
+project folder, so a build is discoverable and resumable from **any** directory — the current working
+directory does not matter. Create the workspace if it's missing and do all of a stage's work inside
+it (including the frontend `src/`, built and deployed from `~/.hostinger/<domain>/src/`).
+
+**The directory name is the domain**, so the files inside it never repeat it, and `~/.hostinger/`
+holds every site you've built — one subdirectory per domain, no collisions.
+
+| File (under `~/.hostinger/<domain>/`) | Written by | Contains |
+|---|---|---|
+| `state.json` | every stage | tool, next stage, Hostinger connector version, timestamps |
+| `connect.json` | connect | tool, account/plan readiness |
+| `brief.md` | refine | refined brief, audience, tone, pages, must-haves |
+| `site.json` | provision | chosen backend, username, install id, all URLs |
+| `content-model.md` | content model | entities, fields, pages, navigation |
+| `design.md` (+ `brand/` logo files) | design | chosen design direction: tokens, type, logo, components, per-page composition, accessibility |
+| `src/` | frontend | the website source implementing `design.md`; framework choice is recorded in `state.json → frontend` |
+| `deploy.json` | deploy | build id, deployed at, live URLs |
+| `events.jsonl` | every stage, via `run-log.mjs` | append-only log of issues, user feedback, skill gaps and wins |
+| `reports/<run>.json` + `.html`, `report.html` | done (or any early stop), via `run-log.mjs` | the build report for each run; `report.html` is the latest |
+
+`state.json` is the minimum you must keep current. **`stage` is the *next* stage to run** (not the
+last completed one), and it does **not** store the domain — the directory is the key. Because
+provision runs in the background, its status lives in its own `provision` field rather than in
+`stage`, so prepare work can advance `stage` while provision is still settling:
+
+```json
+{
+  "tool": "claude-code",
+  "stage": "content_model",
+  "provision": {
+    "status": "in_progress",
+    "domain": "example.com",
+    "started_at": "2026-10-08T10:00:00Z"
+  },
+  "updated_at": "2026-10-08T10:00:00Z"
+}
+```
+
+- `provision` is **absent** until provision fires, `{"status":"in_progress", …}` while the
+  background poll runs, and `{"status":"completed", …}` once `hosting_websites_list-setups` confirms
+  it. `domain` is the poll target.
+- Any **instance-barrier** step (content-model push, frontend data, deploy) must read
+  `provision.status == "completed"` — and re-verify it against the connector — before it runs. A
+  prepare step ignores `provision` entirely.
+- On **resume**, `provision.status` is a hint only: re-poll `hosting_websites_list-setups` to learn
+  the truth, then update the field.
+- `run` (the current run), `history` (one entry per stage or phase, with real start and end
+  times), and `reports_sent` / `reports_rejected` (which copy of each report reached Hostinger) are
+  written **only** by `run-log.mjs`. Leave them alone when you update `state.json` by hand.
+
+---
+
+## Run log and build report
+
+`run-log.mjs` (next to this file) records the run while it happens and turns it into a report at the
+end. Timestamps come from the script, so they're measured, not remembered. It needs only Node.
+Every command is `node <skill>/run-log.mjs <domain> …`, where `<skill>` is the folder this file is
+in. Write it out in full each time (a shell variable holding the command breaks in zsh):
+
+```bash
+node <skill>/run-log.mjs <domain> run-start --tool <tool> --model <model> --skill <skill version>  # check-state, first thing
+node <skill>/run-log.mjs <domain> run-update --kind resume        # check-state, once the route is agreed (or redesign / iterate)
+node <skill>/run-log.mjs <domain> stage-start frontend            # before a stage
+node <skill>/run-log.mjs <domain> stage-end frontend ok_after_retries --note "second framework tried"
+node <skill>/run-log.mjs <domain> stage-start frontend --phase shell   # split stages log each phase
+node <skill>/run-log.mjs <domain> event issue '{"stage":"content_model","symptom":"…","cause":"…","workaround":"…","severity":"medium","resolved":true}'
+node <skill>/run-log.mjs <domain> report --outcome live           # done, or wherever the run stops
+node <skill>/run-log.mjs <domain> report-sent <run>               # after the report was sent (see below)
+node <skill>/run-log.mjs <domain> report-rejected <run>           # the send returned 422
+node <skill>/run-log.mjs <domain> unsent                          # check-state: reports still to send
+node <skill>/run-log.mjs <domain> run-resume --reason "about/contact layout fix"   # follow-up in the same session
+```
+
+**Follow-ups continue the run.** When the user asks for a change after the final report in the
+same session (a layout fix, a copy tweak, a redeploy), that work belongs to the run it follows:
+call `run-resume`, log the feedback and the stages it re-runs as usual, then `report` again. That
+rewrites the same `reports/<run>.json` and `.html`, so you get one report that includes the follow-up,
+not a second report that replaces `report.html`. Use `run-start` only in a new session; check-state
+does that.
+
+`stage-end` results: `ok`, `ok_after_retries`, `ok_with_fixups`, `failed`, `skipped`, `stopped`.
+Stages: `check_state`, `refine`, `provision`, `content_model`, `design`, `frontend`, `validate`,
+`deploy`, `done` (connect has its own `connect.json`). Split stages use `--phase`: provision `fire` /
+`join`, content model `prepare` / `push`, frontend `shell` / `data`.
+
+**Forgot a `stage-start`?** Log it as soon as you notice, with roughly when the stage began:
+`stage-start frontend --started-ago 6m` (or `--started-at <ISO time>`). The same flags work on a
+`stage-end` that has no start. With neither, the script assumes the stage began when the previous one
+ended. Either way the start is marked as estimated in the report. Never log a start and an end
+back to back after the work is done: that records a stage that took no time. If you already did,
+correct it with `stage-fix frontend --started-ago 6m`.
+
+**Log an event the moment it happens**, not at the end — details are gone by then:
+
+| Event | Log it when | Fields (required in bold) |
+|---|---|---|
+| `issue` | something fails, misbehaves, or needs a workaround — including your own mistakes | **stage**, **symptom**, cause, workaround, severity (`high`/`medium`/`low`), resolved, user_had_to_intervene |
+| `feedback` | the user corrects you, rejects something, or changes scope | **stage**, **category** (e.g. `design_rejected`, `layout_bug`, `scope_add`, `wrong_assumption`), **paraphrase** |
+| `skill_gap` | a step is dummy, missing, wrong or silent on what you needed | **skill** (path), **gap** |
+| `good` | something worked notably well or fast | **text** |
+
+Paraphrase the user; don't paste long quotes, file contents, credentials or personal data. Set
+`user_had_to_intervene` when the user had to point the problem out.
 
-## Paths
+**Tokens** go on `report --tokens '<json>'` only if your tool tells you your own usage directly
+(`{"source":"…","requests":…,"input":…,"output":…,"cache_read":…,"cache_write":…,"est_cost_usd":…}`).
+Otherwise leave it out and the report says `{"source":"not reported"}` (not null: the connector rejects a null `tokens`). Never read session transcripts or log
+files to get it.
 
-| What | Path |
-| --- | --- |
-| Plan check + website/domain provisioning | `references/SETUP.md` |
-| Store: seed the backend + the frontend API contract | `references/STORE.md` |
-| WordPress: headless CMS/blog backend + the frontend read contract | `references/WORDPRESS.md` |
-| Deploy: static vs Node.js, archive rules, logs, verify | `references/DEPLOYMENT.md` |
-| Database + runtime: MySQL host per runtime, env vars, what to poll, runtime logs | `references/DATABASE.md` |
+The report is saved to `reports/<run>.json` and `.html`, and `report.html` in the workspace is the
+latest. If a run never reaches its report (the window closed), the next `run-start` closes it as
+`abandoned`, so its log still becomes a report.
 
-## Where the how comes from
+**Send every report to Hostinger.** Sending is part of the flow, so don't ask first; tell the user in
+one line right after the send (see `09-done`). Right after each
+`report` (follow-ups included), read `reports/<run>.json` and pass its contents, unchanged, as the
+arguments of the Hostinger connector tool `hosting_headless_submit-build-report`. Then record the
+result:
 
-The inputSchema returned by search is authoritative for request shapes — read it before calling. Two live sources supersede anything written here when they disagree:
+- **Success:** `report-sent <run>`.
+- **422** (the report doesn't match the schema the endpoint holds): `report-rejected <run>`. Don't
+  resend it.
+- **Anything else** (network error, 5xx, the tool isn't in your connector): do nothing. The next
+  check-state sends it again.
 
-- The ecommerce operation `ecommerce_miscellaneous_custom-storefront-setup-instructions` returns the current storefront integration guide from the server — execute it at the start of any store run.
-- The Hostinger API reference at https://developers.hostinger.com describes every endpoint behind the operations.
+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`.

package/skills/headless/connect/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: hostinger-headless-connect
+description: "Connect step for the Hostinger Headless flow — verify Node, run the bootstrap (reach the Hostinger MCP server + OAuth sign-in), then route to the matching coding-tool skill under tools/ so MCP tools and skills are available before the build steps run. Triggers: connect to Hostinger, set up the Hostinger connector, start a headless build."
+---
+
+# Hostinger Headless Skill — connect
+
+You are a coding agent, and this is a skill for you to execute. Follow the phases below in order.
+
+This skill goal is to help you to connect to Hostinger via MCP. That can be done via Hostinger Connector or adding the MCP via MCP Server.
+
+We support different coding Agentic coding tools such as Claude Code, Codex, Cursor, VS Code...and so on. 
+
+Your goal is to route those tools to their specific skill inside the tools folder ensuring the tool is fully connected.
+
+
+## Phase 0 — Node (the single one prerequisite)
+
+The Hostinger MCP server requires Node ≥ 20. Check it:
+
+```bash
+node -v
+```
+
+If that errors (Node not installed) or prints a version below 20, install or upgrade Node and re-check — do not try to work around it:
+
+- macOS: `brew install node` (or `nvm install 22 && nvm use 22`)
+- Linux: `nvm install 22 && nvm use 22` (or your distro's Node 20+ package)
+- Windows: `winget install OpenJS.NodeJS.LTS` (or download from nodejs.org)
+
+## Phase 1 — Run the bootstrap (deterministic)
+
+Download the bootstrap script, then run it. It verifies the MCP server and handles sign-in, emitting one JSON event per line on stdout. Run it as a background/streaming process and relay its events to the user.
+
+The script is safe and inspectable: it only checks the MCP server via `npx` and drives the OAuth sign-in (a browser flow with a localhost callback) — no other network calls, no filesystem writes. Read it first if your sandbox flags externally-downloaded code.
+
+```bash
+# macOS/Linux:
+curl -fsSL -O https://raw.githubusercontent.com/hostinger/api-mcp-server/main/skills/headless/connect/bootstrap.mjs
+# Windows PowerShell:
+iwr https://raw.githubusercontent.com/hostinger/api-mcp-server/main/skills/headless/connect/bootstrap.mjs -OutFile bootstrap.mjs
+
+node bootstrap.mjs
+```
+
+### Relay these events
+
+The script emits one JSON object per line:
+
+| Event | What to do                                                                                                                                                                                                                           |
+| --- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `mcp_ok` | MCP server reachable — continue.                                                                                                                                                                                                     |
+| `logged_in` | Already authenticated (env token or a previous sign-in) — continue.                                                                                                                                                                  |
+| `awaiting_user` (`verificationUri`) | A browser window should have opened on the user's machine. Show the URL in plain prose and wait for the user to finish signing in. The OAuth callback lands on a localhost port, so the sign-in must be completed on this same machine. |
+| `success` | Bootstrap done — continue to Phase 2. |
+| `mcp_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. Do not improvise a parallel setup by hand. |
+
+If the environment has a `HOSTINGER_API_TOKEN` set (for example CI), the bootstrap reports `logged_in` immediately — no browser needed.
+
+### Sign in or out manually
+
+The bootstrap runs the sign-in for you. To run it directly, or to switch accounts, use the MCP's own commands. `--login` opens the browser to the Hostinger sign-in page, waits for the localhost callback, stores the credentials and exits. `--logout` revokes the stored credentials, so the next sign-in opens the browser again.
+
+```bash
+# With a global install (npm install -g @hostinger/mcp):
+hostinger-api-mcp --login
+hostinger-api-mcp --logout
+
+# Without a global install:
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp --login
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp --logout
+```
+
+Credentials live in `~/.config/hostinger-mcp/credentials.json` (macOS/Linux) or `%APPDATA%\hostinger-mcp\credentials.json` (Windows) and are shared by every Hostinger MCP binary. OAuth works only in stdio mode; `--http` needs `HOSTINGER_API_TOKEN`.
+
+## Phase 2 - Route to the specific tool instructions
+
+| Tool        | Route                           |
+|-------------|---------------------------------|
+| Claude Code | `connect/tools/claude-code.md`  |
+| Codex       | `connect/tools/codex.md`        |
+| Cursor      | `connect/tools/cursor.md`       |
+| VS Code     | `connect/tools/vscode.md`       |
+| Antigravity | `connect/tools/antigravity.md`  |
+| Devin       | `connect/tools/devin.md`        |
+
+If the user's tool isn't listed yet, connect it the generic way (register the Hostinger MCP server
+for that tool, or drive `npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp` over stdio) and continue.
+
+## 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.
+
+> **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
+
+- https://mcpservers.org/servers/hostinger/api-mcp-server
+- https://www.hostinger.com/connector

package/skills/headless/{entry → connect}/bootstrap.mjs

@@ -21,10 +21,15 @@ const fail = (event, extra = {}) => {
 const isWin = process.platform === 'win32';
 const bin = (name) => (isWin ? `${name}.cmd` : name);
 // Run the MCP via npx — no global install, always the latest published version.
-const MCP = [bin('npx'), '-y', '@hostinger/mcp@latest'];
+// Use --package so npx resolves the published package, then invoke the unified binary.
+const MCP = [bin('npx'), '-y', '--package=@hostinger/mcp@latest', 'hostinger-api-mcp'];
+// Node >= 18.20.2 / 20.12.2 refuses to spawn a .cmd/.bat without a shell
+// (CVE-2024-27980), so npx.cmd needs shell:true on Windows. Our args are all
+// fixed literals, so enabling the shell introduces no injection risk.
+const spawnShell = isWin;
 
 function capture(cmd, args) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: false });
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: spawnShell });
   return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
 }
 
@@ -67,7 +72,7 @@ function existingAuth() {
 // prefix — forward it so the agent can show it if the browser didn't open.
 function login() {
   return new Promise((resolve) => {
-    const child = spawn(MCP[0], [...MCP.slice(1), '--login'], { shell: false });
+    const child = spawn(MCP[0], [...MCP.slice(1), '--login'], { shell: spawnShell });
     let diag = '';
     let urlSent = false;
     const collect = (chunk) => {