hostinger-api-mcp 3.27.3 → 3.28.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.28.0 — 2026-11-04
+
+### Also in this release
+
+- Dependencies: `package-lock.json`
+- Bundled agent skills: 14 files
+- Other files: `src/core/skills.js`, `src/core/skills.ts`
+
+## v3.27.4 — 2026-11-03
+
+### Also in this release
+
+- Bundled agent skills: `skills/headless/VERSION`
+
 ## v3.27.3 — 2026-11-03
 
 ### Also in this release

package/gemini-extension.json

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

package/skills/headless/SKILL.md

@@ -58,7 +58,7 @@ The order is sequencial run and check the whole headless flow:
 | — | **connect** — connect the Hostinger connector, auth, get active plan                                               | `connect/SKILL.md` → `connect/tools/<tool>.md` | `connect.json` | no |
 | 1 | **check state** — where does this domain stand? resume / switch / start over                                       | `steps/01-check-state/SKILL.md`                                       | `state.json` | no |
 | 2 | **refine** — discover what the user wants, in conversation                                                         | `steps/02-refine/SKILL.md`                                            | `brief.md` | no |
-| 3 | **provision** — choose the backend from the brief, then provision it                                               | `steps/03-provision/<backend>/SKILL.md`                               | `site.json` | **bg** — fire, then poll in the background |
+| 3 | **provision** — choose the backend from the brief, then provision it                                               | `steps/03-provision/<backend>/SKILL.md`                               | `site.json` | **bg** — fire, then wait at the join |
 | 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** |
@@ -89,7 +89,7 @@ the user rather than improvising the stage from its description.
 The **Instance?** column says whether a stage touches the live backend:
 `no` = pure prepare work that can run during the provision wait;
 `push`/`data`/`yes` = a commit phase that joins the instance barrier;
-`bg` = provision itself, the background task.
+`bg` = provision itself: Hostinger runs the job while you do the prepare work.
 
 **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
@@ -99,8 +99,8 @@ missing step, a failed provision, or a user pause. Every run also saves a **buil
 Waiting for the user's answer to a question is not a run ending: end your turn with the question
 alone, with no final report and no build report.
 
-**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
+**Log the run as you go.** Wrap every stage (and each phase of a split stage) in the run log —
+`run-log.mjs next <stage>` at each boundary — 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
@@ -178,17 +178,37 @@ which of these cases applies and records it, then provision takes the matching p
 3. **User wants a webapp.** Provision is a plain Node.js app host, not headless — `webapp` ignores
    headless shells entirely and is only reached by experimental actions, never the onboarding flow.
 
-Either way the create/install is asynchronous and returns `queued` immediately, then it's polled
-every ~15 s for a few minutes — **what you poll depends on the path**: a fresh
-`hosting_websites_create` is polled with `hosting_websites_list-setups` until `completed`, while a
-shell swap (`wordpress_installations_install`) creates no new setup, so it's polled with
-`wordpress_installations_list` until the `/cms` row is `is_valid`. Don't block on that poll. The
-single rule that makes the overlap safe:
+Either way the create/install is asynchronous and returns `queued` immediately, then it takes a few
+minutes — **what to wait on depends on the path**: a fresh `hosting_websites_create` is `wait.mjs setup`
+(until `hosting_websites_list-setups` says `completed`), while a shell swap
+(`wordpress_installations_install`) creates no new setup, so it's `wait.mjs cms` (until the `/cms` row of
+`wordpress_installations_list` is valid). Run it at the join, not at the fire: by then the prepare work
+has usually outlasted the job, so it returns at once. 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
+> **Fire provision (Hostinger runs it asynchronously), 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 ready (via the
 > backend step's readiness poll — see above). That wait is the *instance barrier*.**
 
+### Waiting on Hostinger: `wait.mjs`
+
+`wait.mjs` (next to this file) waits for a slow Hostinger job in one command, so you don't spend a turn
+on every check:
+
+```bash
+node <skill>/wait.mjs setup <domain>              # a fresh site's setup → completed
+node <skill>/wait.mjs cms <domain> <username>     # a shell swap's WordPress install at /cms → valid
+node <skill>/wait.mjs build <domain> <buildUuid>  # the deploy build → completed, then the root serves 200
+node <skill>/wait.mjs live <domain>               # the root serves 200
+```
+
+Run it in the foreground, with a `--timeout` just under your tool's command limit (e.g. `--timeout 9m`
+when commands may run 10 minutes); on `timed_out`, run the same command again: it picks the job up
+where it is. It prints one JSON line and
+exits 0 with `ok: true` and what it waited for; 1 with `ok: false` when the job failed, timed out
+(`timed_out`, `last_status`) or hit an error that waiting won't fix (`error`); 2 when it couldn't start
+the local Hostinger MCP, with `fallback` naming the connector operation to poll yourself, every ~15 s.
+Never write your own `sleep` loops.
+
 ---
 
 ## State and artifacts
@@ -243,14 +263,15 @@ provision runs in the background, its status lives in its own `provision` field
 }
 ```
 
-- `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.
+- `provision` is **absent** until provision fires, `{"status":"in_progress", …}` from the fire until
+  the join's `wait.mjs` returns `ok: true`, then `{"status":"completed", …}`. `domain` is the wait's
+  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.
+  `provision.status == "completed"` before it runs. The connector is asked twice per run: at
+  check-state (or the provision join that sets `completed`), and in deploy's pre-flight, because deploy
+  overwrites the site. Steps in between trust `state.json`. A prepare step ignores `provision` entirely.
+- On **resume**, `provision.status` is a hint only: check-state re-polls `hosting_websites_list-setups`
+  to learn the truth, then updates the field.
 - Write `state.json` however is easiest, rewriting the whole file included: the run log lives in
   `run-log.json`, which only `run-log.mjs` writes.
 - The **onboarding slug** is how hPanel names the coding tool: `claude` for Claude Code, else
@@ -269,9 +290,10 @@ in. Write it out in full each time (a shell variable holding the command breaks
 ```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> next frontend                  # at a stage boundary: ends the open stage as ok, starts this one
+node <skill>/run-log.mjs <domain> next frontend --phase shell     # split stages log each phase
+node <skill>/run-log.mjs <domain> stage-end frontend ok_after_retries --note "second framework tried"   # any other result, or a note
+node <skill>/run-log.mjs <domain> stage-start frontend            # start without ending anything
 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)
@@ -280,6 +302,12 @@ node <skill>/run-log.mjs <domain> unsent                          # check-state:
 node <skill>/run-log.mjs <domain> run-resume --reason "about/contact layout fix"   # follow-up in the same session
 ```
 
+**Don't spend a turn on the log.** Put each run-log call in the same shell command as the work next
+to it, joined with `&&` (e.g. `node <skill>/run-log.mjs <domain> next deploy && cd … && zip …`), and use
+`next` at a boundary rather than a `stage-end` plus a `stage-start`. When the stage ending wasn't plain
+`ok` or needs a note, put its `stage-end` first in the same command. `next` refuses when two stages are
+open and names them; end them with `stage-end`.
+
 **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

package/skills/headless/VERSION

@@ -1,3 +1,3 @@
-version=3.27.3
-commit=fddd58626392
-built=2026-11-03
+version=3.28.0
+commit=0b30a7c65edb
+built=2026-11-04

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

@@ -48,14 +48,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/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` —
@@ -128,15 +129,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
 
-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.
+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:
+
+- `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 +175,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`
 

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>']
 ```