hostinger-api-mcp 3.27.4 → 3.28.1

package/skills/headless/run-log.mjs

@@ -6,6 +6,7 @@
 //   node run-log.mjs <domain> run-resume [--reason "<text>"]
 //   node run-log.mjs <domain> stage-start <stage> [--phase <phase>] [--started-ago 6m | --started-at <ISO time>]
 //   node run-log.mjs <domain> stage-end <stage> <result> [--phase <phase>] [--note "<text>"] [--started-ago 6m | --started-at <ISO time>]
+//   node run-log.mjs <domain> next <stage> [--phase <phase>]
 //   node run-log.mjs <domain> stage-fix <stage> [--phase <phase>] (--started-ago 6m | --started-at <ISO time>)
 //   node run-log.mjs <domain> event <issue|feedback|skill_gap|good> '<json>'
 //   node run-log.mjs <domain> report [--outcome live|stopped|failed|abandoned] [--tokens '<json>']
@@ -239,6 +240,22 @@ function stageEnd(ws, [stage, result], flags) {
   console.log(`${stage}${phase ? `/${phase}` : ''} ended: ${result}`);
 }
 
+// One call at a stage boundary: ends the open stage (or phase) as ok and starts <stage>, unless the open
+// one is <stage> itself, so re-running a chained `next X && …` doesn't close X as ok. With nothing open
+// it only starts; with more than one open it can't tell which ends, so it refuses.
+function next(ws, [stage], flags) {
+  if (!STAGES.includes(stage)) fail(`unknown stage "${stage}"; one of ${STAGES.join(', ')}`);
+  const log = loadLog(ws);
+  const run = currentRun(log);
+  const open = (log.history ?? []).filter((h) => h.run === run.id && !h.ended_at);
+  const label = (h) => `${h.stage}${h.phase ? ` --phase ${h.phase}` : ''}`;
+  if (open.length > 1) fail(`${open.map(label).join(' and ')} are open; end each with stage-end <stage> <result>, then call next`);
+  const phase = flags.phase ?? null;
+  const [current] = open;
+  if (current && !(current.stage === stage && current.phase === phase)) stageEnd(ws, [current.stage, 'ok'], { phase: current.phase ?? undefined });
+  stageStart(ws, [stage], { phase: flags.phase });
+}
+
 function stageFix(ws, [stage], flags) {
   if (!STAGES.includes(stage)) fail(`unknown stage "${stage}"`);
   const log = loadLog(ws);
@@ -663,6 +680,9 @@ switch (command) {
   case 'stage-end':
     stageEnd(ws, rest, flags);
     break;
+  case 'next':
+    next(ws, rest, flags);
+    break;
   case 'stage-fix':
     stageFix(ws, rest, flags);
     break;
@@ -696,5 +716,5 @@ switch (command) {
     reportRejected(ws, rest);
     break;
   default:
-    fail('command must be run-start, run-update, run-resume, stage-start, stage-end, stage-fix, event, report, unsent, report-sent or report-rejected');
+    fail('command must be run-start, run-update, run-resume, stage-start, stage-end, next, stage-fix, event, report, unsent, report-sent or report-rejected');
 }

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

@@ -32,8 +32,9 @@ present only once provision has fired):
   "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.
+`provision.status` is `in_progress` or `completed` — but it is a **hint** from an earlier session:
+re-verify it against `hosting_websites_list-setups` here (Step 1). See *State and artifacts* in the
+top-level `SKILL.md` for when the connector is asked again.
 
 ---
 
@@ -43,18 +44,14 @@ Before anything else, start a run and the stage (see *Run log and build report*
 `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
+node <skill>/run-log.mjs <domain> run-start --tool <tool> --model <model> --skill <skill version> && \
+node <skill>/run-log.mjs <domain> next check_state && \
+node <skill>/run-log.mjs <domain> unsent
 ```
 
 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
-```
+`unsent` lists the build reports that haven't reached Hostinger yet (that abandoned run, or a send
+that failed last time).
 
 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
@@ -70,7 +67,8 @@ Keep two things separate, and **never guess from a timestamp.**
   `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.
+    either resume prepare work while it finishes or wait for it at the barrier with
+    `wait.mjs setup <domain>` (see *Waiting on Hostinger* in the top-level `SKILL.md`).
   - `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.
@@ -200,7 +198,8 @@ When the intent is ambiguous, **ask** — don't guess. A skipped tool result is
 
 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>"`.
+`redesign` / `iterate`) and end the stage with the route as its note, in one shell command:
+`… run-update --kind resume && … 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

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

@@ -10,9 +10,9 @@ 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
+**This stage is asynchronous.** Provisioning is mostly a wait on Hostinger, so it splits in two: a
+**fire** half (detect + create, returns straight away) and a **join** half (`wait.mjs` in the
+foreground, 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
@@ -98,7 +98,7 @@ So provision has **two entry shapes**, and each subfolder's *detect* step picks
    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
+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)
@@ -118,8 +118,8 @@ asynchronous — fire it, record `provision.in_progress`, and join at the barrie
 > shell from an already-provisioned backend.
 
 Follow the chosen subfolder's `SKILL.md` through **detect + create** (its `hosting_websites_create` call). The
-moment the create is accepted and queued, record it in `state.json` and **return** — do not sit on the
-readiness poll:
+moment the create is accepted and queued, record it in `state.json` and **return** — do not wait for
+it yet:
 
 ```json
 { "stage": "content_model",
@@ -132,7 +132,8 @@ shell). The subfolder's readiness poll, verification and `site.json` are the **j
 ## 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.
+right away, if the agent can't interleave — finish the subfolder's `SKILL.md`: run its `wait.mjs` (it
+returns at once if the job is already done), 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`.
+

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

@@ -17,26 +17,19 @@ Provision a **Hostinger Ecommerce** backend for `<domain>` and prove it is ready
 
 > ## ⚠️ 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:
+> **`hostinger-ecommerce`** group (`ecommerce_*` ops, OAuth-backed, no API token needed). Connect
+> registers it alongside `hostinger`, so its tools are normally already in the session. If they
+> aren't (for example, a tool connected before connect registered both servers), register it now. The
+> command for each tool is in its `connect/tools/<tool>.md`; for Claude Code:
 > ```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
+> claude mcp add hostinger-ecommerce --scope user -- npx --package=@hostinger/mcp@latest hostinger-ecommerce-mcp
 > ```
-> (For other tools, enable the **Ecommerce** MCP in the Hostinger Connector.) A newly added MCP server
-> only loads on a session restart/reconnect.
+> (Or enable the **Ecommerce** MCP in the Hostinger Connector.) A newly added MCP server only loads
+> after a restart, so pause the run with *register, restart, resume* from `connect/SKILL.md`: save
+> state, ask the user to restart the tool and paste the same prompt, and end your turn. Check-state then
+> resumes at provision. Never spawn the server yourself or write a JSON-RPC client to reach it.
 >
-> **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" →
+> Verify the tools work in-session 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.
 
@@ -48,14 +41,17 @@ All website-lifecycle calls go through the `hosting` connector (`execute`); all
 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. If `website_type` is not `headless`
+   → adopt. `running` → record `provision.in_progress` and wait at the join. `failed` → stop, point at hPanel.
+   If `website_type` is not `headless`
    (plain WordPress, Node.js, …), stop and tell the user — don't overwrite another kind of site.
 2. Create (only if **no** site exists): `hosting_websites_create { order_id, type: "headless_ecommerce", domain }`
    — **omit `domain`** for a temporary subdomain: the setup generates one itself and returns it (don't
    call a separate subdomain op first — there's no need in this flow). The response carries the
    generated domain; if it differs from the workspace dir, move
    `~/.hostinger/<old>/` → `<new>/` (if `<new>/` already exists, stop and ask instead of moving
-   into it) and update `brief.md`. Poll `list-setups` to `completed`. `website_type` will be `headless`.
+   into it) and update `brief.md`. Don't wait here. At the join, `node <skill>/wait.mjs setup <domain>`
+   returns once the setup is `completed` (see *Waiting on Hostinger* in the top-level `SKILL.md`).
+   `website_type` will be `headless`.
 
 > **Onboarding handoff — an empty headless shell needs no new website.** If the domain already has an
 > empty headless shell (`website_type: headless`, setup `type: headless_empty`, nothing installed —

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

@@ -57,8 +57,9 @@ All website/database operations below go through the Hostinger connector (`execu
    `~/.hostinger/<new>/`
    (if `<new>/` already exists, stop and ask instead of moving into it),
    update the domain in `brief.md`, and tell the user the new domain.
-3. Poll `hosting_websites_list-setups { "domain": "<domain>" }` every ~15 s until `completed`
-   (typically under a minute; allow a few minutes). `failed` → stop, point at hPanel.
+3. Don't wait here. At the join, `node <skill>/wait.mjs setup <domain>` (see *Waiting on Hostinger* in
+   the top-level `SKILL.md`) returns once the setup is `completed`, usually at once by then. A `failed`
+   setup → stop, point at hPanel.
 
 ## Step 3 — Database (only if the app needs one)
 

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

@@ -64,8 +64,9 @@ All operations below go through the Hostinger connector (`execute`).
    (if `<new>/` already exists, stop and ask instead of moving into it),
    update the domain in `brief.md`, and tell the user the new domain.
    Admin credentials are generated by the platform; never ask the user for a password.
-3. Poll `hosting_websites_list-setups { "domain": "<domain>" }` every ~15 s until `completed`
-   (typically under a minute; allow a few minutes). `failed` → stop, point at hPanel.
+3. Don't wait here. At the join, `node <skill>/wait.mjs setup <domain>` (see *Waiting on Hostinger* in
+   the top-level `SKILL.md`) returns once the setup is `completed`, usually at once by then. A `failed`
+   setup → stop, point at hPanel.
 
 ## Step 2b — Swap an empty headless shell to WordPress (only when onboarding already made the shell)
 
@@ -93,11 +94,9 @@ install WordPress straight into its `/cms` directory. This is the onboarding han
    - A new database is created for the install unless you pass `database.name` of an existing one; the
      generated database counts against the plan's limit.
 3. The call is **asynchronous** — a success response only means the install job was **queued**. This is
-   the *fire*: record `provision.in_progress` and return to prepare work. Poll
-   `wordpress_installations_list { username, domain, ownership: "all" }` (exact row) at the join; when a
-   row with `directory: "cms"` and `is_valid: true` appears, WordPress is ready. Allow 1–2 minutes;
-   `wordpress_installations_list` can lag a few seconds behind the job finishing and return `[]` — retry
-   briefly before failing.
+   the *fire*: record `provision.in_progress` and return to prepare work. At the join,
+   `node <skill>/wait.mjs cms <domain> <username>` returns the `/cms` install row (`directory: "cms"`,
+   valid) once it exists, usually within 1–2 minutes of the install.
 
 ## Step 3 — Verify (all must pass)
 

package/skills/headless/steps/04-content-model/SKILL.md

@@ -96,7 +96,7 @@ not an answer, see *When you ask the user* in the top-level `SKILL.md`):
 | Option | Tool | Backends | Needs the live instance? |
 |---|---|---|---|
 | **A — Hostinger AI image generation** *(default for WordPress / WooCommerce)* | `wordpress_ai-content_generate-images` | WordPress, WordPress + WooCommerce | **yes** — runs at the instance barrier |
-| **B — Unsplash stock photos** *(default for Ecommerce / Webapp; the fallback everywhere)* | Unsplash API, or web search + web fetch | any | no — pure prepare work |
+| **B — Unsplash stock photos** *(default for Ecommerce / Webapp; the fallback everywhere)* | Unsplash API, or web fetch of Unsplash search pages | any | no — pure prepare work |
 
 > **Do not silently fall back to stock on a WordPress site.** On WordPress / WooCommerce the default is
 > **Hostinger AI (Option A)** — on-brand, generated from `design.md`. Using Unsplash on a WordPress build
@@ -165,29 +165,47 @@ runs **at the instance barrier** (after `provision.status == "completed"`), usin
 This is still prepare work and needs no live backend: you pick the photos and record their URLs here,
 and the push phase uploads them.
 
-1. **Find candidates.** Use one photo per article, matching its subject and destination.
-   - With an `UNSPLASH_ACCESS_KEY` in the environment, use the official API:
-     `GET https://api.unsplash.com/search/photos?query=<subject>&orientation=landscape` with header
-     `Authorization: Client-ID <key>`.
-   - Without a key, use web search limited to `unsplash.com` (e.g. "unsplash photo Lisbon tram") and
-     take the photo id from the result URL: the last segment of `unsplash.com/photos/<slug>-<id>`, or
-     the whole segment for `unsplash.com/photos/<id>`.
-2. **Resolve a direct file URL.** With the API, the result's `urls.raw` is the file and `user.name`
-   the photographer; for each photo you keep, also `GET` its `links.download_location` (same header),
-   as the API terms require. Without a key, open the photo page (`https://unsplash.com/photos/<…>`)
-   with your **web-fetch tool** and ask it for the main photo's `images.unsplash.com/photo-<…>` URL,
-   quoted exactly, and the photographer's name. Either way, drop the query string and request a web
-   size: `https://images.unsplash.com/photo-<…>?w=1600&q=80&fm=jpg&fit=max`. Check that it returns
-   200 with `image/jpeg`: the upload ability needs this direct file URL, not the photo page.
-   - Every other `unsplash.com` request (curl on the page, `/photos/<id>/download`, `/napi/…`,
+Source every image in a few batched calls, not a search and a fetch per photo:
+
+1. **Find candidates, a page of them per fetch.** Group the image briefs into a few themes (e.g.
+   "sourdough bread", "bakery interior", "Lisbon street").
+   - With an `UNSPLASH_ACCESS_KEY` in the environment, use the official API, one call per theme:
+     `GET https://api.unsplash.com/search/photos?query=<theme>&orientation=landscape&per_page=20` with
+     header `Authorization: Client-ID <key>`. Each result's `urls.raw` is the file, `alt_description`
+     what it shows and `user.name` the photographer; for each photo you keep, also `GET` its
+     `links.download_location` (same header), as the API terms require.
+   - Without a key, open the theme's search page `https://unsplash.com/s/photos/<theme-with-dashes>`
+     with your **web-fetch tool**, once per theme, and ask it to list every free photo on the page with
+     its `images.unsplash.com/photo-<…>` URL quoted exactly (the part before `?`), the photo page
+     link, the alt text and the photographer. One fetch returns 10–20 candidates. Skip the
+     `plus.unsplash.com/premium_photo-…` results: they are Unsplash+ and not free. Fetch the themes in
+     parallel when your tool allows several calls at once. Fall back to a web search limited to
+     `unsplash.com` plus a fetch of one photo page (`https://unsplash.com/photos/<…>`) only for a
+     subject no search page covers.
+   - Every other `unsplash.com` request (curl on any page, `/photos/<id>/download`, `/napi/…`,
      `/oembed`) hits a bot challenge: a `307` to `/.within.website` (Anubis) or a 401. If your fetch
      tool gets the challenge page too, stop: no user-agent spoofing or other workarounds. On a
      WordPress backend where Option A hasn't already failed, offer it; otherwise ask the user for an
      `UNSPLASH_ACCESS_KEY` or record the gap (step 5).
-3. **Look before you keep it.** Download a small preview (`?w=500`) and view it. Search snippets and
-   fetch summaries only describe the page, and can hand you a related photo's thumbnail instead of
-   the main one; a photo also often isn't quite what its title says. Reject anything off-topic.
-   If nothing fits exactly, take the closest real photo and note the gap rather than mislabel it.
+2. **Check them all in one command.** Pick a candidate per image brief from the alt text, then in one
+   shell command request each web-size URL
+   (`https://images.unsplash.com/photo-<…>?w=1600&q=80&fm=jpg&fit=max`, query string replaced) and
+   confirm 200 `image/jpeg`, and save a small preview (`?w=500`) of each into one folder, e.g.:
+
+   ```bash
+   mkdir -p ~/.hostinger/<domain>/media/previews && cd ~/.hostinger/<domain>/media/previews && \
+   for id in photo-<a> photo-<b>; do
+     curl -s -o /dev/null -w "$id %{http_code} %{content_type}\n" "https://images.unsplash.com/$id?w=1600&q=80&fm=jpg&fit=max"
+     curl -s -o "$id.jpg" "https://images.unsplash.com/$id?w=500&q=60&fm=jpg&fit=max"
+   done
+   ```
+
+   The upload ability needs this direct file URL, not the photo page.
+3. **Look before you keep it.** View the previews, all in one turn where your tool can open several
+   images at once. Alt text from a search page describes the photo better than a search snippet, but
+   a photo often isn't quite what its title says. Reject anything off-topic and take the next
+   candidate from the same list. If nothing fits exactly, take the closest real photo and note the gap
+   rather than mislabel it.
 4. **Write alt text from what the photo shows**, not from the article's image brief. For example,
    use "Shopfronts and parked scooters on a Hanoi street" even if the article is about rain.
 5. **Record it** under each article in `content-model.md`:
@@ -212,7 +230,7 @@ Then update `state.json`: set `stage` to the next prepare stage still to do, fre
 
 ## Push phase — create it the backend's way (needs the instance)
 
-Only once `provision.status == "completed"` (re-verified against `hosting_websites_list-setups`),
+Only once `provision.status == "completed"` (see *State and artifacts* in the top-level `SKILL.md`),
 route on the brief's **Suggested backend** and follow that subfolder, which maps the helper onto the
 live backend — for WordPress, through the per-site WP MCP's ability tools (the installation JWT
 authenticates that MCP session; `wp/v2` REST is the public read surface, not a write path for the

package/skills/headless/steps/04-content-model/ecommerce/SKILL.md

@@ -12,9 +12,9 @@ OAuth). Prices are **integers in minor units** (cents) and live on **variants**.
 **In:** `content-model.md` (prepared catalog), `site.json` (`ecommerce.store_id`). **Out:** products +
 images created in the store; ids recorded back into `content-model.md`.
 
-> If the `hostinger-ecommerce` MCP tools aren't available, don't stop — see the prerequisite in
-> `../../03-provision/ecommerce/SKILL.md` (add the server, and if you can't reconnect your session,
-> drive the stdio server directly rather than blocking).
+> If the `hostinger-ecommerce` MCP tools aren't available, follow the prerequisite in
+> `../../03-provision/ecommerce/SKILL.md`: register the server, then pause with *register, restart,
+> resume* from `connect/SKILL.md`. Never drive the server yourself over stdio.
 
 ## Step 1 — Create products (idempotent)
 

package/skills/headless/steps/04-content-model/wordpress/SKILL.md

@@ -5,8 +5,7 @@ description: "Push phase of Step 4 for a headless WordPress backend: open an aut
 
 # headless-step-content-model-wordpress
 
-**Push phase — needs the live instance.** Run only after `provision.status == "completed"` (re-verify
-against `hosting_websites_list-setups`). It maps the backend-agnostic `content-model.md` onto real
+**Push phase — needs the live instance.** Run only after `provision.status == "completed"`. It maps the backend-agnostic `content-model.md` onto real
 WordPress objects.
 
 **In:** `content-model.md`, `site.json` (both prepared earlier), generated media under

package/skills/headless/steps/07-validate/SKILL.md

@@ -16,9 +16,9 @@ description: "Step 7 (validate) of the Hostinger Headless flow. OPTIONAL quick g
 
 ## 1 — Instance status (always, quick)
 
-`provision.status == "completed"` **and** re-verify against the connector:
-`hosting_websites_list-setups { "domain": "<domain>" }`, exact-match the row → `completed`. Anything
-else → not ready; return to the instance barrier, don't deploy.
+`provision.status == "completed"` in `state.json`. Anything else → not ready; return to the instance
+barrier, don't deploy. Deploy's pre-flight asks the connector again (see *State and artifacts* in the
+top-level `SKILL.md`).
 
 ## 2 — Backend API status (WordPress / WooCommerce / Ecommerce, always, quick)
 

package/skills/headless/steps/08-deploy/SKILL.md

@@ -21,7 +21,7 @@ This is an **instance-barrier** step: run it only after `provision.status == "co
 > settings passed exactly as the table below says. Run it from the project, since it links the current directory:
 > `cd ~/.hostinger/<domain>/src && hostinger up --domain <domain> --type nodejs --app-type <appType> --output-directory <dir> --build-script build --node-version 22 --package-manager npm --yes --format json`.
 > It uploads, builds, waits and returns `data.buildUuid` and `data.buildState`; add `--no-wait` to
-> return at once and poll with `hostinger hosting nodejs build <domain> <uuid>`. Then continue at
+> return at once and wait with `node <skill>/wait.mjs build <domain> <uuid>`. Then continue at
 > "Verify" below. Recent CLI versions see that the site is headless (`data.headless: true`) and
 > deploy only its Node.js frontend, leaving `/cms` alone; still pass the settings above.
 
@@ -74,8 +74,9 @@ framework's correct values** — don't rely on auto-detection (it returns null
 
 ## Step 1 — Pre-flight
 
-1. **Instance live.** `provision.status == "completed"`, re-verified with
-   `hosting_websites_list-setups { "domain": "<domain>" }`.
+1. **Instance live (the deploy gate).** `provision.status == "completed"`, re-verified with
+   `hosting_websites_list-setups { "domain": "<domain>" }`: deploy overwrites the site root, so it never
+   trusts `state.json` alone.
 2. **Build output exists locally** (the framework's output dir — e.g. `.next/`, `dist/`, `.output/`) and
    the project builds clean (frontend/validate already did this). If not, go back.
    - **Next.js 16+:** `package.json`'s `build` script is `next build --webpack`, not plain `next build` —
@@ -96,23 +97,44 @@ Zip the project **source** with `package.json` at the archive root. **Include**
 `package.json`, `package-lock.json`, `.nvmrc`. **Exclude** `node_modules/`, the build output
 (`.next/`, `dist/`, `out/`), `.git/`, and any `.htaccess` — the server installs and builds from source.
 
+> ## ⚠️ Write the archive outside `~/.hostinger/` (the deploy refuses it there)
+> `hosting_deploy` refuses any `path` under a hidden folder at the top of the home directory
+> (`~/.hostinger`, `~/.config`, …) with *"it is, or contains, a home, system or credentials location"*:
+> a deploy publishes what it reads, so the connector protects dotfolders that can hold tokens. That
+> covers both `~/.hostinger/<domain>/app.zip` **and** the `~/.hostinger/<domain>/src/` directory
+> itself, so neither can be passed as `path`. Keep the source in the workspace as usual, but write the
+> archive to a fresh temp directory and pass that. Don't copy the archive somewhere else after a
+> refusal, and don't move `src/` out of the workspace.
+
 ```bash
+# macOS/Linux — the OS temp dir is outside the home directory
 cd ~/.hostinger/<domain>/src
-zip -r -X ../app.zip . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'
+DEPLOY_DIR=$(mktemp -d)
+zip -r -X "$DEPLOY_DIR/app.zip" . -x 'node_modules/*' '.next/*' 'dist/*' 'out/*' '.git/*' '**/.htaccess'
+echo "$DEPLOY_DIR/app.zip"   # the absolute path to pass as `path` in Step 3
+```
+
+```powershell
+# Windows PowerShell — %TEMP% sits under AppData, which the deploy also refuses; use a folder on the system drive
+cd $HOME\.hostinger\<domain>\src
+$DeployDir = Join-Path $env:SystemDrive "hostinger-deploy\<domain>"; New-Item -ItemType Directory -Force $DeployDir | Out-Null
+tar -a -cf "$DeployDir\app.zip" --exclude=node_modules --exclude=.next --exclude=dist --exclude=out --exclude=.git --exclude=.htaccess .
+"$DeployDir\app.zip"        # the absolute path to pass as `path` in Step 3
 ```
 
+Delete the temp directory once the build in Step 4 is `completed`.
+
 ## Step 3 — Deploy (one shot: settings + upload + build)
 
 Pass the framework's build settings **inline** on the deploy call — there is no separate settings step.
-`path` is the archive from Step 2 (or the source directory itself; `hosting_deploy` archives a directory
-for you, skipping `node_modules/`, `.git/` and `.env`, but it does **not** read `.gitignore`, so the
-build output must already be absent).
+`path` is the absolute path of the archive from Step 2, in its temp directory. Never pass a path under
+`~/.hostinger/`, the `src/` directory included: the deploy refuses it (see Step 2).
 
 ```json
 { "operation": "hosting_deploy",
   "params": {
     "domain": "<domain>",
-    "path": "/absolute/path/to/.hostinger/<domain>/app.zip",
+    "path": "<absolute path printed in Step 2, e.g. /var/folders/…/tmp.XXXX/app.zip>",
     "type": "nodejs",
     "appType": "<framework appType, e.g. next>",
     "outputDirectory": "<framework output dir, e.g. .next>",
@@ -128,15 +150,26 @@ website root** (expected) and keeps `/cms` intact. `type` is always `"nodejs"` f
 **never `"static"`** (see the gate below). Passing `appType`/`outputDirectory` explicitly is what
 keeps the root from serving 403 (see the rule above).
 
-## Step 4 — Poll to completion
+## Step 4 — Wait for the build and the live root
+
+Wait for it in one command (see *Waiting on Hostinger* in the top-level `SKILL.md`):
+
+```bash
+node <skill>/wait.mjs build <domain> <buildUuid>
+```
+
+It waits for `hosting_get-deployment` to report the build `completed`, then for `https://<domain>/` to
+serve 200. What its result means here:
 
-Poll `hosting_get-deployment { "domain": "<domain>", "buildUuid": "<buildUuid>" }` with backoff until
-`build.state` is `completed`. On `failed`, the same response carries the end of the build log and the
-failure analysis — read it, fix locally, re-archive and redeploy (pass `fromLine`, the line count from
-the previous call, to read only new log output). `hosting_get-deployment` also returns the build settings
-stored for the site: `appType`/`outputDirectory`/`nodeVersion` should echo what you passed; if they read
-`null`, the settings didn't take — fix the deploy call before continuing. For an SSR app that built but
-hangs, `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.
+- `ok: true`: the build is done and the root serves 200. Go on to Step 5.
+- `ok: false` with `build.state: failed`: read `log_tail` (the end of the build log) and `analysis`, fix
+  locally, re-archive and redeploy (pass `fromLine` to `hosting_get-deployment` to read only new log
+  output).
+- `ok: false` with `build settings missing`: the settings didn't take (the root would 403 for good). Fix
+  the deploy call and redeploy.
+- `ok: false` with `timed_out`: `last_status` says whether the build was still running or the root
+  wasn't serving 200 yet (see Step 5's note on a 403). For an SSR app that built but hangs,
+  `hosting_nodejs_restart-application { username, domain }` recovers the server without a rebuild.
 
 ## Step 5 — Verify the live site (all must pass)
 
@@ -163,9 +196,10 @@ hangs, `hosting_nodejs_restart-application { username, domain }` recovers the se
 >   200 is a passing, complete deploy. Never fail or hold the deploy because checkout is unavailable.
 > - **Webapp:** no content backend at all — the whole root is the app. Skip the check; `/cms` won't resolve.
 
-A `completed` build whose root 403s almost always means the build settings weren't passed to
-`hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a stale root;
-re-check after ~30 s.
+The root check is already done when `wait.mjs build` returned `ok: true`; check the rest in one shell
+command (`curl` each URL). A `completed` build whose root 403s almost always means the build settings
+weren't passed to `hosting_deploy` (null settings) — pass them and redeploy. Caching can briefly serve a
+stale root; re-check after ~30 s.
 
 ## Step 6 — Record `deploy.json`
 
@@ -211,6 +245,6 @@ still deploys as `type: "nodejs"` with its `appType` — the framework's static
 that way, and `/cms` is preserved. If a flow ever tells you to deploy a headless site as `type:
 "static"`, you are on a stale/legacy skill copy — stop and re-pull the latest skills.
 
-`hosting_deploy` on the local server is the only path: give its `path` either the source **directory** (it archives it for
-you) or a local **archive** (`zip`, `tar`, `tar.gz`, `tgz`, `7z`) — there is no separate upload or build
-step to fall back to.
+`hosting_deploy` on the local server is the only path: give its `path` a local **archive** (`zip`, `tar`,
+`tar.gz`, `tgz`, `7z`) written outside `~/.hostinger/` as in Step 2. There is no separate upload or
+build step to fall back to.

package/skills/headless/steps/09-done/SKILL.md

@@ -160,8 +160,9 @@ from `run-log.json`, events from `events.jsonl`) into `reports/<run>.json` and `
 HTML to `report.html` in the workspace:
 
 ```bash
-node <skill>/run-log.mjs <domain> event good '{"text":"<something that went well>"}'   # one per thing, if not logged yet
-node <skill>/run-log.mjs <domain> stage-end done ok
+# one shell command; one `event good` per thing that went well, if not logged yet
+node <skill>/run-log.mjs <domain> event good '{"text":"<something that went well>"}' && \
+node <skill>/run-log.mjs <domain> stage-end done ok && \
 node <skill>/run-log.mjs <domain> report --outcome <live|stopped|failed> [--tokens '<json>']
 ```