@hostinger/mcp 4.0.4 → 4.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/gemini-extension.json +1 -1
  3. package/package.json +1 -1
  4. package/server.json +2 -2
  5. package/skills/headless/SKILL.md +9 -16
  6. package/skills/headless/VERSION +2 -2
  7. package/skills/headless/steps/01-check-state/SKILL.md +9 -51
  8. package/skills/headless/steps/02-refine/SKILL.md +4 -22
  9. package/skills/headless/steps/03-provision/SKILL.md +6 -54
  10. package/skills/headless/steps/03-provision/wordpress/SKILL.md +9 -147
  11. package/skills/headless/steps/04-content-model/SKILL.md +4 -72
  12. package/skills/headless/steps/04-content-model/ecommerce/SKILL.md +1 -1
  13. package/skills/headless/steps/04-content-model/images-unsplash.md +74 -0
  14. package/skills/headless/steps/04-content-model/wordpress/contact-form.md +76 -11
  15. package/skills/headless/steps/04-content-model/wordpress/woocommerce.md +48 -1
  16. package/skills/headless/steps/05-design/SKILL.md +6 -63
  17. package/skills/headless/steps/05-design/bring-your-own-frontend.md +11 -0
  18. package/skills/headless/steps/05-design/keep-look.md +37 -0
  19. package/skills/headless/steps/06-frontend/SKILL.md +15 -56
  20. package/skills/headless/steps/06-frontend/bring-your-own-frontend.md +13 -0
  21. package/skills/headless/steps/06-frontend/ecommerce.md +16 -0
  22. package/skills/headless/steps/07-validate/SKILL.md +3 -13
  23. package/skills/headless/steps/08-deploy/SKILL.md +8 -33
  24. package/skills/headless/steps/09-done/SKILL.md +7 -22
  25. package/src/core/skills.js +77 -42
  26. package/src/core/skills.ts +77 -42
  27. package/src/servers/agency-hosting.js +1 -1
  28. package/src/servers/agency-hosting.ts +1 -1
  29. package/src/servers/agent-readiness.js +1 -1
  30. package/src/servers/agent-readiness.ts +1 -1
  31. package/src/servers/all.js +1 -1
  32. package/src/servers/all.ts +1 -1
  33. package/src/servers/billing.js +1 -1
  34. package/src/servers/billing.ts +1 -1
  35. package/src/servers/dns.js +1 -1
  36. package/src/servers/dns.ts +1 -1
  37. package/src/servers/domains.js +1 -1
  38. package/src/servers/domains.ts +1 -1
  39. package/src/servers/ecommerce.js +1 -1
  40. package/src/servers/ecommerce.ts +1 -1
  41. package/src/servers/gpu.js +1 -1
  42. package/src/servers/gpu.ts +1 -1
  43. package/src/servers/horizons.js +1 -1
  44. package/src/servers/horizons.ts +1 -1
  45. package/src/servers/hosting.js +1 -1
  46. package/src/servers/hosting.ts +1 -1
  47. package/src/servers/mail.js +1 -1
  48. package/src/servers/mail.ts +1 -1
  49. package/src/servers/reach.js +1 -1
  50. package/src/servers/reach.ts +1 -1
  51. package/src/servers/vps.js +1 -1
  52. package/src/servers/vps.ts +1 -1
  53. package/src/servers/wordpress.js +1 -1
  54. package/src/servers/wordpress.ts +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,13 @@ Generated at release time from the diff between the previous and current
4
4
  build. Tool changes are listed individually; everything else is summarised
5
5
  by area.
6
6
 
7
+ ## v4.0.5 — 2026-11-16
8
+
9
+ ### Also in this release
10
+
11
+ - Bundled agent skills: 20 files
12
+ - Other files: `src/core/skills.js`, `src/core/skills.ts`
13
+
7
14
  ## v4.0.4 — 2026-11-16
8
15
 
9
16
  ### Also in this release
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hostinger-api-mcp",
3
- "version": "4.0.4",
3
+ "version": "4.0.5",
4
4
  "description": "Hostinger API — manage domains, DNS, hosting, VPS, billing and more from Gemini CLI.",
5
5
  "mcpServers": {
6
6
  "hostinger": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hostinger/mcp",
3
- "version": "4.0.4",
3
+ "version": "4.0.5",
4
4
  "mcpName": "io.github.hostinger/hostinger-api-mcp",
5
5
  "description": "MCP server for Hostinger API",
6
6
  "repository": {
package/server.json CHANGED
@@ -17,12 +17,12 @@
17
17
  "url": "https://github.com/hostinger/api-mcp-server",
18
18
  "source": "github"
19
19
  },
20
- "version": "4.0.4",
20
+ "version": "4.0.5",
21
21
  "packages": [
22
22
  {
23
23
  "registryType": "npm",
24
24
  "identifier": "@hostinger/mcp",
25
- "version": "4.0.4",
25
+ "version": "4.0.5",
26
26
  "transport": {
27
27
  "type": "stdio"
28
28
  },
@@ -164,26 +164,19 @@ hostinger.com has already created the website before you run, so the domain *has
164
164
  but an instance existing does **not** mean provision is done or can be skipped. `check_state` works out
165
165
  which of these cases applies and records it, then provision takes the matching path:
166
166
 
167
- 1. **An empty headless shell already exists for the domain (the common onboarding case).** Onboarding
168
- creates the website first — an **empty headless shell** (`hosting_websites_create { type:
169
- "headless_empty" }`): `website_type` is `headless`, but **no backend is installed** (no WordPress at
170
- `/cms`, no store). This still goes through provision, which **adopts the shell and swaps it to the
171
- chosen backend** (the backend is picked in refine first): WordPress is installed into the shell's
172
- `/cms` with `wordpress_installations_install { type: "headless" }`, or the shell is adopted as the
173
- Ecommerce storefront host. **Never skip provision for a shell, and never create a second site.** See
174
- the provision router's *Onboarding handoff*.
175
- 2. **No instance exists at all** (the user ran the headless flow without onboarding provisioning
176
- anything). Provision creates a fresh headless instance with `hosting_websites_create` using the
177
- chosen backend's own `type`.
167
+ 1. **An empty headless shell already exists for the domain (the common onboarding case).** Provision
168
+ **adopts the shell and swaps it to the chosen backend** (the backend is picked in refine first).
169
+ **Never skip provision for a shell, and never create a second site.** See the provision router's
170
+ *Onboarding handoff*.
171
+ 2. **No instance exists at all.** Provision creates a fresh headless instance with
172
+ `hosting_websites_create` using the chosen backend's own `type`.
178
173
  3. **User wants a webapp.** Provision is a plain Node.js app host, not headless — `webapp` ignores
179
174
  headless shells entirely and is only reached by experimental actions, never the onboarding flow.
180
175
 
181
176
  Either way the create/install is asynchronous and returns `queued` immediately, then it takes a few
182
- minutes — **what to wait on depends on the path**: a fresh `hosting_websites_create` is `wait.mjs setup`
183
- (until `hosting_websites_list-setups` says `completed`), while a shell swap
184
- (`wordpress_installations_install`) creates no new setup, so it's `wait.mjs cms` (until the `/cms` row of
185
- `wordpress_installations_list` is valid). Run it at the join, not at the fire: by then the prepare work
186
- has usually outlasted the job, so it returns at once. The single rule that makes the overlap safe:
177
+ minutes; the backend's provision step names the `wait.mjs` command to run at the join, not at the fire.
178
+ By then the prepare work has usually outlasted the job, so it returns at once. The single rule that
179
+ makes the overlap safe:
187
180
 
188
181
  > **Fire provision (Hostinger runs it asynchronously), then do every stage's prepare work while it settles. The
189
182
  > moment a step must write to the live instance, it waits for provision to report ready (via the
@@ -1,3 +1,3 @@
1
- version=4.0.4
2
- commit=c1f91b71a56b
1
+ version=4.0.5
2
+ commit=e1ee2eda6108
3
3
  built=2026-11-16
@@ -14,27 +14,8 @@ This step owns all resume/position logic — no other stage second-guesses it.
14
14
  Nothing in this step creates, provisions, deploys, or deletes anything. It reads and guides. Its
15
15
  only writes to Hostinger are unsent build reports (Step 0) and the tool-connected event (Step 3).
16
16
 
17
- ---
18
-
19
- ## Where state lives
20
-
21
- Everything for a domain lives under the global site workspace **`~/.hostinger/<domain>/`** — one
22
- directory per domain, under the user's home (`~` = `$HOME`), **not** the current working directory.
23
- The directory name **is** the domain, so `state.json` inside does not store it. Because it's global,
24
- this domain's build is resumable from any directory.
25
-
26
- `state.json` shape (`stage` is the *next* stage to run; `provision` is the background task's status,
27
- present only once provision has fired):
28
-
29
- ```json
30
- { "tool": "claude-code", "stage": "content_model",
31
- "provision": { "status": "in_progress", "domain": "<domain>", "started_at": "…" },
32
- "updated_at": "…" }
33
- ```
34
-
35
- `provision.status` is `in_progress` or `completed` — but it is a **hint** from an earlier session:
36
- re-verify it against `hosting_websites_list-setups` here (Step 1). See *State and artifacts* in the
37
- top-level `SKILL.md` for when the connector is asked again.
17
+ Everything for this domain lives in its global workspace `~/.hostinger/<domain>/`; the files and the
18
+ `state.json` shape are in *State and artifacts* in the top-level `SKILL.md`.
38
19
 
39
20
  ---
40
21
 
@@ -56,8 +37,6 @@ that failed last time).
56
37
  Each line is `<run> <path>`. For each, send the file through `hosting_headless_submit-build-report`
57
38
  and record the result, as described in *Run log and build report* in the top-level `SKILL.md`. One
58
39
  try each. Don't ask first and say nothing about it to the user. Don't let a failure hold up this step.
59
- Check-state runs once per session. A follow-up after the final report, in the same session, doesn't
60
- come back here: it calls `run-resume` (see *Run log and build report* in the top-level `SKILL.md`).
61
40
 
62
41
  ## Step 1 — Is a build actively running right now? (check this before anything else)
63
42
 
@@ -121,22 +100,13 @@ Query the Hostinger connector — the local files are never trusted on their own
121
100
  a sandboxed shell), try it one more time the way that environment allows, such as requesting
122
101
  approval or network access, then go on. Ignore any other failure, such as a non-2xx response from
123
102
  Hostinger: no retry, nothing more said to the user, and the run carries on unchanged.
124
- - **How far did it get?** If the site exists, check its setup via
125
- `hosting_websites_list-setups { "domain": "<domain>" }` (exact-match the row the same way):
126
- - `status: completed` → provisioned; then, depending on backend, check whether a build has succeeded.
127
- - `status: running` → still provisioning (see Step 1).
128
- - `status: failed` → provisioning stopped before finishing → route to **provision** to self-heal.
129
- - **Is it an empty headless shell from onboarding?** A `headless` site whose setup is `completed` is
130
- **not necessarily finished** — onboarding now creates the website *before* the build runs, as an
131
- **empty headless shell** (`hosting_websites_create { type: "headless_empty" }`): `website_type`
132
- is `headless` but **no backend is installed** (no WordPress at `/cms`, no store). Tell a shell from a
133
- real backend the same way provision does: within 24 h the setup `type` is `headless_empty`; otherwise
134
- `wordpress_installations_list { username, domain, ownership: "all" }` returns **no** `/cms` row and
135
- there is no `site.json` recording a backend. An empty shell means **provision has not chosen or
136
- installed a backend yet** — this is a **new build** that happens to already own its website, not a
137
- finished or resumable one. Route it to **refine** (choose the backend), then **provision** adopts the
138
- shell and swaps it to that backend (see the provision router's *Onboarding handoff*). Never create a
139
- second site, and never skip provision for it.
103
+ - **Is it an empty headless shell from onboarding?** A `headless` site with no backend installed (no
104
+ WordPress at `/cms`, no store) is an **empty headless shell**: within 24 h its setup `type` is
105
+ `headless_empty`; otherwise `wordpress_installations_list { username, domain, ownership: "all" }`
106
+ returns **no** `/cms` row and there is no `site.json` recording a backend. It is a **new build** that
107
+ happens to already own its website, not a finished or resumable one. Route it to **refine** (choose
108
+ the backend), then **provision** adopts the shell and swaps it to that backend (provision's subfolder
109
+ repeats this check before swapping). Never create a second site, and never skip provision for it.
140
110
 
141
111
  Reconcile with the local state. **When they disagree, reality wins** and the local `stage` is
142
112
  corrected.
@@ -209,15 +179,3 @@ Then:
209
179
  forces an unnecessary "is another window running?" question on the next run. Always release the lock
210
180
  on a clean stop; it exists only to mark an actively-running session. A stop is still the end of a
211
181
  run: give the final report and save the build report (`09-done`).
212
-
213
- ---
214
-
215
- ## Invariants
216
-
217
- - **One directory per domain.** The domain is the key; state files never repeat it.
218
- - **Only this domain's workspace.** Never list `~/.hostinger/` or open another site's workspace (see
219
- *State and artifacts* in the top-level `SKILL.md`).
220
- - **Never create a second site** on a domain that already has one.
221
- - **Never re-provision or overwrite a live site.** Recovery is forward-only.
222
- - **Reality beats local state**, always.
223
- - **When ambiguous, ask.**
@@ -146,9 +146,8 @@ calendar backend, user-generated content), say plainly that the headless flow do
146
146
  and record it under **Out of scope** — don't promise it.
147
147
 
148
148
  > **A contact form *is* supported (WordPress backends).** If the user wants one, keep it in
149
- > **Must-haves** and name it "Contact form". Provision installs **Contact Form 7** on `/cms` and the
150
- > frontend wires a contact page whose form emails the site owner through WordPress's built-in
151
- > `wp_mail()` — no third-party service and no API keys. It's **opt-in**: built only when the brief asks
149
+ > **Must-haves** and name it "Contact form": provision installs **Contact Form 7** and the frontend
150
+ > wires a contact page that emails the site owner. It's **opt-in**: built only when the brief asks
152
151
  > for it. (A form that needs accounts, payments or a booking calendar is still out of scope — this is a
153
152
  > plain name/email/message enquiry form.)
154
153
 
@@ -261,8 +260,6 @@ can. Then update `state.json`:
261
260
  The **Suggested backend** section is the contract with `03-provision/SKILL.md`, which routes on it.
262
261
  Its first line must be exactly one of `**WordPress**`, `**Ecommerce**`, `**WordPress + Ecommerce**`,
263
262
  `**WordPress + WooCommerce**` or `**Webapp**`, followed by an em dash and the one-line reason.
264
- `**WordPress + WooCommerce**` is the WordPress backend with the WooCommerce store turned on — provision
265
- routes it to the `wordpress` subfolder with the store enabled (it is **not** a separate backend).
266
263
 
267
264
  ## `brief.md` template
268
265
 
@@ -324,23 +321,8 @@ the app reads — names only, never values>
324
321
  **<Bring your own frontend | Agent designs and builds>** — <one line>. <When "Bring your own frontend":
325
322
  how they want to drive design/code; the project's path is under **Existing project**. When "Agent designs and builds": leave the design + frontend steps to run as
326
323
  normal; with **Existing project** filled, the frontend starts from that app's source and rebuilds its UI
327
- to design.md.> The design step and the frontend step both read this: **Bring your own frontend** → design
328
- defers to the user and frontend builds on their project; **Agent designs and builds** → both run as normal.
324
+ to design.md.>
329
325
 
330
326
  ## Rendering
331
- **<SSR | SSG>** — <reason>. Rules: **Ecommerce requires SSR** and **WordPress + WooCommerce requires
332
- SSR** (carts/checkout need per-request rendering — any SSR framework works; Next.js is the default, not
333
- a requirement); **WordPress may be SSG (Astro)** when the site is mostly static and rarely changes,
334
- otherwise **SSR**. Default when unsure: **Next.js SSR**.
335
- ```
336
-
337
- ## Example — WordPress + Ecommerce
338
-
339
- > A ceramicist sells around 30 handmade pieces and writes a monthly studio journal.
340
-
341
- ```markdown
342
- ## Suggested backend
343
- **WordPress + Ecommerce** — sells ~30 products with checkout, and the owner publishes a monthly
344
- studio journal they want to edit themselves.
345
- Confirmed by the user.
327
+ **<SSR | SSG>** — <reason; the rules are in Step 4's *Then set rendering*>.
346
328
  ```
@@ -10,14 +10,6 @@ matching subfolder, which provisions it.
10
10
 
11
11
  **In:** `brief.md`. **Out:** `site.json` (written by the subfolder).
12
12
 
13
- **This stage is asynchronous.** Provisioning is mostly a wait on Hostinger, so it splits in two: a
14
- **fire** half (detect + create, returns straight away) and a **join** half (`wait.mjs` in the
15
- foreground, verify, write `site.json`). Fire it, record `provision.in_progress`, then go do the prepare work of
16
- the other stages (content-model prepare, frontend shell) while it settles. Only cross back to
17
- the join half when an instance-barrier step needs the live backend. See *Background provision & the
18
- instance barrier* in the top-level `SKILL.md`. An agent that can't interleave simply does fire and
19
- join back-to-back — still correct, just no overlap.
20
-
21
13
  ## Step 1 — Route on the suggested backend
22
14
 
23
15
  Read the brief's **Suggested backend** section:
@@ -25,22 +17,13 @@ Read the brief's **Suggested backend** section:
25
17
  | Suggested backend | Follow |
26
18
  |---|---|
27
19
  | WordPress | `wordpress/SKILL.md` |
28
- | WordPress + WooCommerce | `wordpress/SKILL.md` **with the WooCommerce store on** (see below) |
20
+ | WordPress + WooCommerce | `wordpress/SKILL.md` **with the WooCommerce store on** (its Step 5; `site.json → backend` stays `"wordpress"`) |
29
21
  | Ecommerce | `ecommerce/SKILL.md` |
30
22
  | Webapp | `webapp/SKILL.md` |
31
23
 
32
24
  If the section is missing or names something else, go back to **refine** — don't pick one here.
33
25
  Tell the user the backend and its one-line reason before provisioning.
34
26
 
35
- > **WordPress + WooCommerce is the WordPress backend with a store — not a new backend.** Route it to
36
- > `wordpress/SKILL.md` and follow that recipe's **optional WooCommerce tail** (install + activate the
37
- > `woocommerce` plugin and verify the store endpoints; the catalog is seeded later through the per-site WP
38
- > MCP's native `wc-*` abilities — no custom plugin, no consumer key). `site.json → backend` stays
39
- > `"wordpress"`; the store is recorded under `site.json → woocommerce` (`enabled: true`). Everything else
40
- > downstream that routes on
41
- > `wordpress` (content-model push, deploy's `/cms` preservation, done's wp-admin login) then works
42
- > unchanged.
43
-
44
27
  > **Supported backends: `wordpress` (optionally with a WooCommerce store), `ecommerce` and `webapp`.**
45
28
  > `webapp` is a plain Node.js app host (an empty website — no CMS, no store, no `/cms`) for any app/SPA
46
29
  > that brings its own code and data; it never installs WordPress. PocketBase is not available in this
@@ -54,24 +37,9 @@ Tell the user the backend and its one-line reason before provisioning.
54
37
 
55
38
  ## Onboarding handoff — swap an existing empty headless shell (do this before creating anything)
56
39
 
57
- Onboarding can create the website **before** you ever run, then paste the build prompt into this agent.
58
- When it does, the domain already has an **empty headless shell**: a website set up with
59
- `hosting_websites_create { type: "headless_empty" }` — `website_type` is `headless`, but **nothing
60
- is installed** (no WordPress at `/cms`, no store). It is the hosting slot only, waiting for a backend.
61
-
62
- So provision has **two entry shapes**, and each subfolder's *detect* step picks between them:
63
-
64
- - **An empty headless shell already exists for the domain → adopt it and *swap* it to the chosen
65
- backend. Never call `hosting_websites_create` again, never create a second site.** The swap is backend-specific:
66
- - **WordPress** → install WordPress **into the existing shell's `/cms`** with
67
- `wordpress_installations_install { type: "headless" }` (it rewrites the root `.htaccess` and marks
68
- the site headless-WordPress). Do **not** use `hosting_websites_create { type: "headless_wordpress" }` — that is
69
- only for creating a fresh site.
70
- - **Ecommerce** → the empty headless shell **is** the storefront host already (a `headless_ecommerce`
71
- website installs no store engine either). Adopt it as the frontend host and go straight to creating
72
- the store + custom sales channel.
73
- - **No site exists for the domain at all → create it fresh, exactly as each subfolder defines today**
74
- (`hosting_websites_create` with the backend's own `type`).
40
+ Onboarding can create the website **before** you ever run, as an **empty headless shell**
41
+ (`hosting_websites_create { type: "headless_empty" }`: `website_type` is `headless`, but **nothing
42
+ is installed**). The single-instance gate in Step 2 is the checklist.
75
43
 
76
44
  > **Webapp is not part of this handoff at all.** `webapp` is **not** reached on the usual onboarding
77
45
  > flow — it is only triggered by experimental actions — so it **ignores headless instances entirely**:
@@ -85,22 +53,6 @@ So provision has **two entry shapes**, and each subfolder's *detect* step picks
85
53
  > stop and tell the user the domain already has a headless instance, rather than leaving the build split
86
54
  > across two sites.
87
55
 
88
- **How to tell an empty shell from an already-provisioned backend** (both read `website_type: headless`):
89
-
90
- 1. Exact-match the domain row in `hosting_websites_list` — if there is **no** row, nothing exists → create fresh.
91
- 2. Within 24 h of onboarding, `hosting_websites_list-setups` still shows the setup `type`
92
- (`headless_empty` = empty shell; `headless_wordpress` = WordPress already; `headless_ecommerce` = an
93
- ecommerce host). Beyond 24 h the setup drops off — fall back to the backend probe:
94
- 3. `wordpress_installations_list { username, domain, ownership: "all" }` — a row with `directory: "cms"`
95
- and `is_valid: true` means WordPress is **already** installed (adopt, don't swap); **no** such row on
96
- a `headless` site means the shell is still empty and WordPress must be swapped in. A local `site.json`
97
- with a recorded backend means a previous run already provisioned — trust reality over it, but it tells
98
- you not to expect an empty shell.
99
-
100
- This only changes *detect*. Everything after the swap (verify, `site.json`, the WooCommerce tail, the
101
- fire/join split) is identical to a fresh provision. A swap that installs WordPress is still
102
- asynchronous — fire it, record `provision.in_progress`, and join at the barrier just like a fresh create.
103
-
104
56
  ## Step 2 — Fire (don't block)
105
57
 
106
58
  > **Single-instance gate — pass all four before you create anything:**
@@ -114,8 +66,8 @@ asynchronous — fire it, record `provision.in_progress`, and join at the barrie
114
66
  > 4. **A row of a different kind** (`website_type` not `headless`) → **stop and tell the user**; never
115
67
  > overwrite it.
116
68
  >
117
- > This is the whole of *Onboarding handoff* above, as one checklist. See it for how to tell an empty
118
- > shell from an already-provisioned backend.
69
+ > `wordpress/SKILL.md` Step 1 and `ecommerce/SKILL.md` Step 1 say how to tell an empty shell from an
70
+ > already-provisioned backend.
119
71
 
120
72
  Follow the chosen subfolder's `SKILL.md` through **detect + create** (its `hosting_websites_create` call). The
121
73
  moment the create is accepted and queued, record it in `state.json` and **return** — do not wait for
@@ -9,14 +9,6 @@ Create the headless WordPress backend for `<domain>` and prove it is ready. One
9
9
  every headless site out identically: WordPress in `public_html/cms`, Hostinger AI Assistant + MCP
10
10
  adapter, site marked `headless`. **Out:** `site.json`.
11
11
 
12
- > **WordPress + WooCommerce?** This same recipe serves it. When the brief's **Suggested backend** is
13
- > `**WordPress + WooCommerce**`, provision the WordPress site exactly as below, then run the **optional
14
- > WooCommerce tail in Step 5** (install + activate the `woocommerce` plugin and verify the store
15
- > endpoints; the catalog is seeded in content-model via the per-site WP MCP).
16
- > WooCommerce is a plugin on this WordPress install, **not** a separate backend: `site.json → backend`
17
- > stays `"wordpress"` and the store is recorded under `site.json → woocommerce`. For a plain WordPress
18
- > brief, skip Step 5 entirely.
19
-
20
12
  All operations below go through the Hostinger connector (`execute`).
21
13
 
22
14
  > **Fire vs join (background provision).** Step 1, plus the queuing call — `hosting_websites_create`
@@ -34,8 +26,8 @@ All operations below go through the Hostinger connector (`execute`).
34
26
  2. **No exact row** → nothing exists on this domain → **create fresh** (Step 2).
35
27
  3. **A row exists.** If `website_type` is **not** `headless`, stop and tell the user — this domain
36
28
  already hosts a different kind of site (plain WordPress, Node.js, builder, …); never overwrite it.
37
- If it **is** `headless`, work out whether WordPress is already installed or the shell is still empty
38
- (see the router's *Onboarding handoff*): check `hosting_websites_list-setups { "domain": "<domain>" }`
29
+ If it **is** `headless`, work out whether WordPress is already installed or the shell is still empty:
30
+ check `hosting_websites_list-setups { "domain": "<domain>" }`
39
31
  (exact row) and `wordpress_installations_list { username, domain, ownership: "all" }` (exact row):
40
32
  - Setup `running` → provisioning is underway → skip to Step 2's poll.
41
33
  - Setup `failed` → tell the user and point them at hPanel; do **not** call `hosting_websites_create` again yourself.
@@ -124,8 +116,8 @@ If a check fails: retry once after ~30 s; if it still fails, stop and point the
124
116
  Every headless WordPress site gets **Yoast SEO** (`wordpress-seo`) installed and activated by default,
125
117
  so per-page title/description/Open Graph/JSON-LD come from a maintained plugin's `yoast_head_json`
126
118
  rather than being hand-generated from each item's content by the frontend. This is **join-half** work
127
- (needs the live `/cms` install), so run it once `provision.status == "completed"`, the same way as the
128
- WooCommerce tail. Tell the user in one line that SEO (Yoast) is being set up; if they explicitly don't
119
+ (needs the live `/cms` install), so run it once `provision.status == "completed"`, the same way as
120
+ Step 5. Tell the user in one line that SEO (Yoast) is being set up; if they explicitly don't
129
121
  want it, skip this step and record `seo.enabled: false` — but the default is to install it.
130
122
 
131
123
  1. **Install + activate Yoast** (management MCP, async — poll, never blind-retry):
@@ -142,93 +134,12 @@ want it, skip this step and record `seo.enabled: false` — but the default is t
142
134
  provision over SEO: if the install can't be confirmed after one retry, record `seo.enabled: false`,
143
135
  tell the user, and let the frontend fall back to generating tags from content.
144
136
 
145
- ## Step 5 — WooCommerce store *(only for a `WordPress + WooCommerce` brief — skip otherwise)*
146
-
147
- Run this only when the brief's **Suggested backend** is `**WordPress + WooCommerce**`. It turns the
148
- headless WordPress site into a headless **store**: WooCommerce is the `woocommerce` plugin on this same
149
- `/cms` install — **not a separate backend**. This is **join-half** work (needs the live instance), so run
150
- it once `provision.status == "completed"`. The authoritative data-layer reference is
151
- [`../../04-content-model/wordpress/woocommerce.md`](../../04-content-model/wordpress/woocommerce.md).
152
-
153
- > **No custom plugin — the catalog is driven through the per-site WP MCP.** A custom plugin can't be
154
- > installed into a headless `/cms` from a coding agent, so there is **no seed/config plugin and no REST
155
- > consumer key in this flow.** Instead, the Hostinger AI Assistant (the per-site WP MCP, same JWT session
156
- > content-model uses) exposes **native WooCommerce abilities** — `wc-products-*`, `wc-product-categories-*`,
157
- > `wc-coupons-*`, `wc-orders-*`, `media-upload-from-url`, `wp-settings-*`. Provision just **installs
158
- > WooCommerce and verifies the store endpoints**; the catalog + coupons are seeded in the content-model
159
- > push through those abilities (see the cookbook).
160
-
161
- 1. **Install + activate WooCommerce** (management MCP, async — poll, never blind-retry):
162
- - `wordpress_plugins_install { username, software: <install_id>, plugins: ["woocommerce"] }`
163
- - Poll `wordpress_plugins_list-installed { username, software }` until `woocommerce` shows `active`
164
- (install + activate can complete together), or activate it with
165
- `wordpress_plugins_activate { username, software, plugin: "woocommerce" }`.
166
- - Confirm with `wordpress_plugins_check-if-woo-commerce-is-installed { domain: "<domain>" }`. Allow a
167
- moment for WooCommerce's installer to create its tables and the Shop/Cart/Checkout pages.
168
- - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
169
- succeeded** (seen on both `plugins_install` and `jwt-token`). Treat a 500 as "verify, don't assume":
170
- poll `list-installed` / re-check before retrying, and never fire a second install blindly.
171
- 2. **Verify the store endpoints (public, no auth):**
172
-
173
- | Check | How | Expect |
174
- |---|---|---|
175
- | WooCommerce active | `wordpress_plugins_check-if-woo-commerce-is-installed { domain }` | installed + active |
176
- | Store API answers | `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` | 200 (empty until content-model seeds — fine) |
177
- | Both namespaces loaded | `GET https://<domain>/cms/wp-json/` → `namespaces` | contains `wc/store/v1` **and** `wc/v3` |
178
-
179
- Pretty permalinks are on by default on a headless install, so the Store API resolves immediately; if a
180
- store route ever 404s, the permalink structure is the thing to check.
181
-
182
- > **Checkout needs owner setup — treat it like the Ecommerce payment gate.** A fresh WooCommerce install
183
- > has **no payment gateway and no shipping zone enabled**, and that configuration is **not reachable from
184
- > the headless tooling** (there is no payment/shipping MCP ability, and `wp-settings-update` only writes
185
- > standard WP settings). So **checkout is unavailable until the owner enables a payment method + shipping
186
- > in wp-admin** (hand them the one-click login in Step 6). Record `woocommerce.payment_enabled: false`
187
- > accordingly. This is **not a build failure**: the catalog, product pages, client-side cart and coupon
188
- > application all work headlessly — the downstream frontend renders a graceful disabled-checkout state and
189
- > never calls `/checkout` while `payment_enabled` is `false` (see content-model + frontend). Never ask the
190
- > user for payment credentials. Store currency and address (`woocommerce_*` options) likewise aren't
191
- > settable headlessly — they follow the install default and the owner can change them in wp-admin.
137
+ ## Step 5 — Store and contact form *(only when the brief has them — skip otherwise)*
192
138
 
193
- ## Step 5b — Contact form (Contact Form 7) *(only when the brief's Must-haves include a contact form — skip otherwise)*
194
-
195
- Run this only when the brief's **Must-haves** include a contact form. It installs **Contact Form 7**
196
- (`contact-form-7`) on this same `/cms` install, so the frontend can render a contact page whose form
197
- emails the site owner through WordPress's built-in `wp_mail()` — no third-party service and no API keys.
198
- Like Yoast/WooCommerce this is **join-half** work: run it once `provision.status == "completed"`. The form
199
- itself (id + fields + recipient) — and a tiny **spam-guard plugin** that makes a honeypot work headlessly —
200
- are resolved/deployed in the content-model push — see
201
- [`../../04-content-model/wordpress/contact-form.md`](../../04-content-model/wordpress/contact-form.md).
202
-
203
- > **Why CF7 and not a bespoke mailer.** A contact form is maintained, spam-hardened functionality worth
204
- > reusing rather than reinventing (you *can* deploy a custom plugin to a headless `/cms` — see the
205
- > content-model cookbook — but you needn't write your own mailer). CF7 is a wordpress.org-slug plugin,
206
- > installs through the same management MCP as Yoast, and ships a **public, unauthenticated** submit
207
- > endpoint (`POST /cms/wp-json/contact-form-7/v1/contact-forms/<id>/feedback`). The frontend and `/cms`
208
- > are same-origin, so the browser posts to it directly — no proxy, no CORS, no secret on the client.
209
-
210
- 1. **Install + activate CF7** (management MCP, async — poll, never blind-retry):
211
- - `wordpress_plugins_install { username, software: <install_id>, plugins: ["contact-form-7"] }`
212
- - Poll `wordpress_plugins_list-installed { username, software }` until `contact-form-7` shows `active`
213
- (install + activate can complete together), or activate it with
214
- `wordpress_plugins_activate { username, software, plugin: "contact-form-7" }`.
215
- - **Don't install the `contact-form-7-honeypot` add-on.** It only acts when a `[honeypot]` form-tag is
216
- present in the form — a wp-admin edit the headless agent can't make — so on the default form it does
217
- nothing. Headless spam protection instead comes from a small **spam-guard plugin deployed in the
218
- content-model push** (it hooks `wpcf7_spam`); see the cookbook.
219
- - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
220
- succeeded**. Treat a 500 as "verify, don't assume": poll `list-installed` before retrying, and
221
- never fire a second install blindly.
222
- 2. **Verify** `GET https://<domain>/cms/wp-json/` lists the **`contact-form-7/v1`** namespace, then
223
- record `contact_form.enabled: true` in `site.json` (Step 6). If the install can't be confirmed after
224
- one retry, record `contact_form.enabled: false`, tell the user in one line, and let the frontend
225
- render the contact page without a form (graceful — not a build failure). Don't fail provision over it.
226
-
227
- The owner's email is **CF7's default recipient** (`[_site_admin_email]`, the admin address from
228
- install) — fine out of the box, so "does Hostinger set up the email?" is **yes** for basic delivery via
229
- `wp_mail`. Deliverability (SPF/DKIM) is most reliable when that address is a mailbox **on the same
230
- domain**; the content-model push keeps the default recipient and validate sends a test submission to
231
- confirm mail actually leaves. Never ask the user for mail credentials.
139
+ - **A store** (the brief's **Suggested backend** is `**WordPress + WooCommerce**`): follow
140
+ [`../../04-content-model/wordpress/woocommerce.md`](../../04-content-model/wordpress/woocommerce.md) §0.
141
+ - **A contact form** (the brief's **Must-haves** include a contact form): follow
142
+ [`../../04-content-model/wordpress/contact-form.md`](../../04-content-model/wordpress/contact-form.md) §0 to install Contact Form 7 (`contact-form-7`).
232
143
 
233
144
  ## Step 6 — Record `site.json`
234
145
 
@@ -261,52 +172,3 @@ confirm mail actually leaves. Never ask the user for mail credentials.
261
172
 
262
173
  No passwords or tokens in `site.json`. When the user needs wp-admin, mint a one-click link with
263
174
  `wordpress_login_create-links { username, software: <install_id> }` — never hand over a password.
264
-
265
- **For a `WordPress + WooCommerce` brief, also add a `woocommerce` block and the store URLs** (the
266
- `backend` field still stays `"wordpress"`):
267
-
268
- ```json
269
- {
270
- "woocommerce": {
271
- "enabled": true,
272
- "seeded_via": "per-site-wp-mcp",
273
- "currency": "<currency_code from GET {store_api}/products or the install default>",
274
- "payment_enabled": false,
275
- "checkout_setup": "owner enables a payment method + shipping in wp-admin"
276
- },
277
- "urls": {
278
- "store_api": "https://<domain>/cms/wp-json/wc/store/v1",
279
- "wc_rest_api": "https://<domain>/cms/wp-json/wc/v3"
280
- }
281
- }
282
- ```
283
-
284
- **For a brief with a contact form (CF7 installed in Step 5b), also add a `contact_form` block.**
285
- Provision records only `enabled` + `plugin` here; the content-model push fills `form_id`,
286
- `feedback_url`, `fields` and `honeypot_field` once it resolves the form and deploys the spam guard:
287
-
288
- ```json
289
- {
290
- "contact_form": {
291
- "enabled": true,
292
- "plugin": "contact-form-7",
293
- "form_id": null,
294
- "feedback_url": null,
295
- "fields": [],
296
- "honeypot_field": null,
297
- "recipient": "site-admin-email"
298
- }
299
- }
300
- ```
301
-
302
- `form_id` / `feedback_url` / `fields` / `honeypot_field` stay `null` / `[]` until content-model resolves the form (the
303
- submit URL is `https://<domain>/cms/wp-json/contact-form-7/v1/contact-forms/<form_id>/feedback`).
304
- `recipient` is informational — CF7's `To` is `[_site_admin_email]`; no address, token or secret is
305
- stored in `site.json`.
306
-
307
- `rest_api` stays `wp/v2` (the WordPress content contract, for the blog/pages on the same site);
308
- `store_api` is the public storefront surface (browse/cart/coupons/checkout, no auth). `wc_rest_api`
309
- (`wc/v3`) is recorded only as the surface the **owner's own** integrations use with a consumer key they
310
- generate in wp-admin — **this flow never creates or stores a key** (the catalog is seeded through the
311
- per-site WP MCP's `wc-*` abilities; the storefront uses the public Store API). `payment_enabled` starts
312
- `false` and flips to `true` only once a gateway + shipping are configured — no secrets in `site.json`.
@@ -115,7 +115,7 @@ you use.**
115
115
 
116
116
  **During the prepare wait, write an image brief for each image** into `content-model.md` no matter the
117
117
  option (subject, `image_type`, aspect, and the alt text you expect). Option B can also *fetch* the
118
- photo now (below); Option A only generates once the instance exists, so its briefs wait for the barrier.
118
+ photo now (see Option B); Option A only generates once the instance exists, so its briefs wait for the barrier.
119
119
 
120
120
  #### Option A — Hostinger AI image generation (WordPress backends)
121
121
 
@@ -156,80 +156,12 @@ runs **at the instance barrier** (after `provision.status == "completed"`), usin
156
156
  right before the push, and put each `url` in its article's or product's `image` in `content.json`
157
157
  (with `alt` and `filename`).
158
158
 
159
- On `failed`, retry once with a tightened prompt; if it fails again, fall back to Option B and note
160
- the gap. Never block the whole push on a single image.
159
+ On `failed`, retry once with a tightened prompt; if it fails again, fall back to Option B ([`images-unsplash.md`](images-unsplash.md))
160
+ and note the gap. Never block the whole push on a single image.
161
161
 
162
162
  #### Option B — stock photos from Unsplash (any backend, no instance)
163
163
 
164
- This is still prepare work and needs no live backend: you pick the photos and record their URLs here,
165
- and the push phase uploads them.
166
-
167
- Source every image in a few batched calls, not a search and a fetch per photo:
168
-
169
- 1. **Find candidates, a page of them per fetch.** Group the image briefs into a few themes (e.g.
170
- "sourdough bread", "bakery interior", "Lisbon street").
171
- - With an `UNSPLASH_ACCESS_KEY` in the environment, use the official API, one call per theme:
172
- `GET https://api.unsplash.com/search/photos?query=<theme>&orientation=landscape&per_page=20` with
173
- header `Authorization: Client-ID <key>`. Each result's `urls.raw` is the file (its `photo-…`
174
- part, before `?`, is the `<file id>`), `id` the `<page id>`, `alt_description` what it shows and
175
- `user.name` the photographer; for each photo you keep, also `GET` its
176
- `links.download_location` (same header), as the API terms require.
177
- - Without a key, open the theme's search page `https://unsplash.com/s/photos/<theme-with-dashes>`
178
- with your **web-fetch tool**, once per theme, with this prompt (a short fixed answer keeps the
179
- fetch fast):
180
-
181
- ```text
182
- List up to 12 free photos on this page, one line each, in this exact format and nothing else:
183
- <file id> | <page id> | <alt text> | <photographer>
184
- <file id> is the photo-… part of its images.unsplash.com URL, copied exactly, before any "?".
185
- <page id> is the part after unsplash.com/photos/ in its photo page link.
186
- Skip plus.unsplash.com/premium_photo-… results: they are Unsplash+ and not free.
187
- ```
188
-
189
- Fetch the themes in parallel when your tool allows several calls at once. Fall back to a web
190
- search limited to `unsplash.com` plus a fetch of one photo page (`https://unsplash.com/photos/<…>`)
191
- only for a subject no search page covers.
192
- - Every other `unsplash.com` request (curl on any page, `/photos/<id>/download`, `/napi/…`,
193
- `/oembed`) hits a bot challenge: a `307` to `/.within.website` (Anubis) or a 401. If your fetch
194
- tool gets the challenge page too, stop: no user-agent spoofing or other workarounds. On a
195
- WordPress backend where Option A hasn't already failed, offer it; otherwise ask the user for an
196
- `UNSPLASH_ACCESS_KEY` or record the gap (step 5).
197
- 2. **Check them all in one command.** Pick a candidate per image brief from its alt text, then in one
198
- shell command request each web-size URL
199
- (`https://images.unsplash.com/<file id>?w=1600&q=80&fm=jpg&fit=max`, query string replaced) and
200
- confirm 200 `image/jpeg`, and save a small preview (`?w=500`) of each into one folder, e.g.:
201
-
202
- ```bash
203
- mkdir -p ~/.hostinger/<domain>/media/previews && cd ~/.hostinger/<domain>/media/previews && \
204
- for id in <file id> <file id>; do
205
- 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"
206
- curl -s -o "$id.jpg" "https://images.unsplash.com/$id?w=500&q=60&fm=jpg&fit=max"
207
- done
208
- ```
209
-
210
- The upload ability needs this direct file URL, not the photo page.
211
- 3. **Look before you keep it.** View the previews, all in one turn where your tool can open several
212
- images at once. Alt text from a search page describes the photo better than a search snippet, but
213
- a photo often isn't quite what its title says. Reject anything off-topic and take the next
214
- candidate from the same list. If nothing fits exactly, take the closest real photo and note the gap
215
- rather than mislabel it.
216
- 4. **Write alt text from what the photo shows**, not from the article's image brief. For example,
217
- use "Shopfronts and parked scooters on a Hanoi street" even if the article is about rain.
218
- 5. **Record it** under each article in `content-model.md` (on WordPress, in the article's `image` in
219
- `content.json` instead: `url`, `alt`, `filename`, and the credit as `caption`):
220
-
221
- ```markdown
222
- Image: https://images.unsplash.com/<file id>?w=1600&q=80&fm=jpg&fit=max
223
- Image credit: <Photographer> — https://unsplash.com/photos/<page id> (Unsplash License)
224
- Image alt: <what the photo shows>
225
- Image file: <site>-<subject>.jpg
226
- ```
227
-
228
- If you can't get a real photo, write `Image gap: <reason>` in place of these lines and tell the
229
- user. Never substitute drawn or generated images without saying so.
230
-
231
- Unsplash photos are free to use under the Unsplash License. Still credit the photographer: the push
232
- phase stores "Photo by <Photographer> on Unsplash" as the image caption.
164
+ Follow [`images-unsplash.md`](images-unsplash.md). It is prepare work and needs no live backend.
233
165
 
234
166
  Then update `state.json`: set `stage` to the next prepare stage still to do, fresh `updated_at`. Do
235
167
  **not** advance past the barrier here.
@@ -38,7 +38,7 @@ reuse existing ids. For each product in the helper:
38
38
  `ecommerce_products_upload-and-attach-image { store_id, product_id, image_url, is_thumbnail: true }` —
39
39
  fetches the image from a public URL and attaches it (raster only, no SVG, ≤15MB, HTTPS, ≤1 redirect).
40
40
  Unsplash direct URLs (`https://images.unsplash.com/photo-…?w=1200&q=80&fm=jpg&fit=max`) work directly.
41
- Source images as in the parent `../SKILL.md` (Unsplash). The store stores its own CDN copy
41
+ Source images as in [`../images-unsplash.md`](../images-unsplash.md). The store stores its own CDN copy
42
42
  (`cdn.zyrosite.com`), so the storefront never depends on the source URL.
43
43
 
44
44
  > Idempotency: check the product's existing `images`/`thumbnail` before attaching so a re-run doesn't pile