@hostinger/mcp 4.0.4 → 4.0.6

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 (56) hide show
  1. package/CHANGELOG.md +13 -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/runtime.js +1 -1
  26. package/src/core/runtime.ts +1 -1
  27. package/src/core/skills.js +77 -42
  28. package/src/core/skills.ts +77 -42
  29. package/src/servers/agency-hosting.js +1 -1
  30. package/src/servers/agency-hosting.ts +1 -1
  31. package/src/servers/agent-readiness.js +1 -1
  32. package/src/servers/agent-readiness.ts +1 -1
  33. package/src/servers/all.js +1 -1
  34. package/src/servers/all.ts +1 -1
  35. package/src/servers/billing.js +1 -1
  36. package/src/servers/billing.ts +1 -1
  37. package/src/servers/dns.js +1 -1
  38. package/src/servers/dns.ts +1 -1
  39. package/src/servers/domains.js +1 -1
  40. package/src/servers/domains.ts +1 -1
  41. package/src/servers/ecommerce.js +1 -1
  42. package/src/servers/ecommerce.ts +1 -1
  43. package/src/servers/gpu.js +1 -1
  44. package/src/servers/gpu.ts +1 -1
  45. package/src/servers/horizons.js +1 -1
  46. package/src/servers/horizons.ts +1 -1
  47. package/src/servers/hosting.js +1 -1
  48. package/src/servers/hosting.ts +1 -1
  49. package/src/servers/mail.js +1 -1
  50. package/src/servers/mail.ts +1 -1
  51. package/src/servers/reach.js +1 -1
  52. package/src/servers/reach.ts +1 -1
  53. package/src/servers/vps.js +1 -1
  54. package/src/servers/vps.ts +1 -1
  55. package/src/servers/wordpress.js +1 -1
  56. package/src/servers/wordpress.ts +1 -1
@@ -0,0 +1,74 @@
1
+ # headless — Option B: stock photos from Unsplash (any backend, no instance)
2
+
3
+ Read from [`SKILL.md`](SKILL.md) *Images* when the user picks stock photos, the backend isn't
4
+ WordPress, or Hostinger AI generation (Option A) failed twice. Step numbers below are this file's.
5
+
6
+ This is still prepare work and needs no live backend: you pick the photos and record their URLs (step 5),
7
+ and the push phase uploads them.
8
+
9
+ Source every image in a few batched calls, not a search and a fetch per photo:
10
+
11
+ 1. **Find candidates, a page of them per fetch.** Group the image briefs into a few themes (e.g.
12
+ "sourdough bread", "bakery interior", "Lisbon street").
13
+ - With an `UNSPLASH_ACCESS_KEY` in the environment, use the official API, one call per theme:
14
+ `GET https://api.unsplash.com/search/photos?query=<theme>&orientation=landscape&per_page=20` with
15
+ header `Authorization: Client-ID <key>`. Each result's `urls.raw` is the file (its `photo-…`
16
+ part, before `?`, is the `<file id>`), `id` the `<page id>`, `alt_description` what it shows and
17
+ `user.name` the photographer; for each photo you keep, also `GET` its
18
+ `links.download_location` (same header), as the API terms require.
19
+ - Without a key, open the theme's search page `https://unsplash.com/s/photos/<theme-with-dashes>`
20
+ with your **web-fetch tool**, once per theme, with this prompt (a short fixed answer keeps the
21
+ fetch fast):
22
+
23
+ ```text
24
+ List up to 12 free photos on this page, one line each, in this exact format and nothing else:
25
+ <file id> | <page id> | <alt text> | <photographer>
26
+ <file id> is the photo-… part of its images.unsplash.com URL, copied exactly, before any "?".
27
+ <page id> is the part after unsplash.com/photos/ in its photo page link.
28
+ Skip plus.unsplash.com/premium_photo-… results: they are Unsplash+ and not free.
29
+ ```
30
+
31
+ Fetch the themes in parallel when your tool allows several calls at once. Fall back to a web
32
+ search limited to `unsplash.com` plus a fetch of one photo page (`https://unsplash.com/photos/<…>`)
33
+ only for a subject no search page covers.
34
+ - Every other `unsplash.com` request (curl on any page, `/photos/<id>/download`, `/napi/…`,
35
+ `/oembed`) hits a bot challenge: a `307` to `/.within.website` (Anubis) or a 401. If your fetch
36
+ tool gets the challenge page too, stop: no user-agent spoofing or other workarounds. On a
37
+ WordPress backend where Option A hasn't already failed, offer it; otherwise ask the user for an
38
+ `UNSPLASH_ACCESS_KEY` or record the gap (step 5).
39
+ 2. **Check them all in one command.** Pick a candidate per image brief from its alt text, then in one
40
+ shell command request each web-size URL
41
+ (`https://images.unsplash.com/<file id>?w=1600&q=80&fm=jpg&fit=max`, query string replaced) and
42
+ confirm 200 `image/jpeg`, and save a small preview (`?w=500`) of each into one folder, e.g.:
43
+
44
+ ```bash
45
+ mkdir -p ~/.hostinger/<domain>/media/previews && cd ~/.hostinger/<domain>/media/previews && \
46
+ for id in <file id> <file id>; do
47
+ 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"
48
+ curl -s -o "$id.jpg" "https://images.unsplash.com/$id?w=500&q=60&fm=jpg&fit=max"
49
+ done
50
+ ```
51
+
52
+ The upload ability needs this direct file URL, not the photo page.
53
+ 3. **Look before you keep it.** View the previews, all in one turn where your tool can open several
54
+ images at once. Alt text from a search page describes the photo better than a search snippet, but
55
+ a photo often isn't quite what its title says. Reject anything off-topic and take the next
56
+ candidate from the same list. If nothing fits exactly, take the closest real photo and note the gap
57
+ rather than mislabel it.
58
+ 4. **Write alt text from what the photo shows**, not from the article's image brief. For example,
59
+ use "Shopfronts and parked scooters on a Hanoi street" even if the article is about rain.
60
+ 5. **Record it** under each article in `content-model.md` (on WordPress, in the article's `image` in
61
+ `content.json` instead: `url`, `alt`, `filename`, and the credit as `caption`):
62
+
63
+ ```markdown
64
+ Image: https://images.unsplash.com/<file id>?w=1600&q=80&fm=jpg&fit=max
65
+ Image credit: <Photographer> — https://unsplash.com/photos/<page id> (Unsplash License)
66
+ Image alt: <what the photo shows>
67
+ Image file: <site>-<subject>.jpg
68
+ ```
69
+
70
+ If you can't get a real photo, write `Image gap: <reason>` in place of these lines and tell the
71
+ user. Never substitute drawn or generated images without saying so.
72
+
73
+ Unsplash photos are free to use under the Unsplash License. Still credit the photographer: the push
74
+ phase stores "Photo by <Photographer> on Unsplash" as the image caption.
@@ -6,12 +6,53 @@ submitted from the **decoupled frontend**, sends the enquiry to the site owner b
6
6
  WordPress's built-in `wp_mail()` — no third-party form service, no API keys, no secret on the client.
7
7
 
8
8
  **Contact Form 7 is not a separate backend.** It is the `contact-form-7` plugin on the same headless
9
- WordPress install at `/cms` (installed in the provision step). This cookbook is the authoritative home for
9
+ WordPress install at `/cms` (installed at provision, §0). This cookbook is the authoritative home for
10
10
  the contact-form data layer: how to **resolve the form** (content-model push), **deploy a spam guard**,
11
11
  what the **frontend submits** (Step 6), and how **validate** proves mail actually leaves.
12
12
 
13
13
  ---
14
14
 
15
+ ## 0 — Provision: install, verify, record `site.json`
16
+
17
+ Read from [`../../03-provision/wordpress/SKILL.md`](../../03-provision/wordpress/SKILL.md) Step 5. Like Yoast this is **join-half** work: run it once
18
+ `provision.status == "completed"`.
19
+
20
+ 1. **Install + activate CF7** (management MCP, async — poll, never blind-retry):
21
+ - `wordpress_plugins_install { username, software: <install_id>, plugins: ["contact-form-7"] }`
22
+ - Poll `wordpress_plugins_list-installed { username, software }` until `contact-form-7` shows `active`
23
+ (install + activate can complete together), or activate it with
24
+ `wordpress_plugins_activate { username, software, plugin: "contact-form-7" }`.
25
+ - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
26
+ succeeded**. Treat a 500 as "verify, don't assume": poll `list-installed` before retrying, and
27
+ never fire a second install blindly.
28
+ 2. **Verify** `GET https://<domain>/cms/wp-json/` lists the **`contact-form-7/v1`** namespace, then
29
+ record `contact_form.enabled: true` in `site.json` (provision Step 6). If the install can't be confirmed after
30
+ one retry, record `contact_form.enabled: false`, tell the user in one line, and let the frontend
31
+ render the contact page without a form (graceful — not a build failure). Don't fail provision over it.
32
+
33
+ Then add the `contact_form` block to `site.json` (provision Step 6). Provision records only `enabled` +
34
+ `plugin` here; §2 fills `form_id`, `feedback_url`, `fields` and `honeypot_field` once it resolves the form
35
+ and deploys the spam guard:
36
+
37
+ ```json
38
+ {
39
+ "contact_form": {
40
+ "enabled": true,
41
+ "plugin": "contact-form-7",
42
+ "form_id": null,
43
+ "feedback_url": null,
44
+ "fields": [],
45
+ "honeypot_field": null,
46
+ "recipient": "site-admin-email"
47
+ }
48
+ }
49
+ ```
50
+
51
+ `recipient` is informational — CF7's `To` is `[_site_admin_email]`; no address, token or secret is
52
+ stored in `site.json`.
53
+
54
+ ---
55
+
15
56
  ## 1 — Why CF7, and why it works headlessly
16
57
 
17
58
  You **could** deploy a custom plugin into the headless `/cms` and write a bespoke mailer (see
@@ -67,7 +108,7 @@ its **numeric form id** (and, if you tailored the form, its field names) to buil
67
108
 
68
109
  The default field names are `your-name`, `your-email`, `your-subject`, `your-message`. (A full test
69
110
  submission that confirms both the id and the field names — and that mail actually sends — belongs to
70
- **validate**, so you send just one real email; see §4.)
111
+ **validate**, so you send just one real email; see §5.)
71
112
 
72
113
  2. **(Optional) tailor the form — owner-side.** The headless tooling can't edit the CF7 form (no REST
73
114
  ability reaches it). If the design needs different fields, keep the default form for the build and note
@@ -167,7 +208,7 @@ sends a decoy field (empty for humans), and the guard flags the submission as sp
167
208
 
168
209
  > **Nonce note.** CF7's built-in spam check also flags nonce failure, but nonce verification is **inactive
169
210
  > for logged-out visitors by default** — which is why a plain headless submission returns `mail_sent`, not
170
- > `spam`. The guard adds the honeypot on top. Confirm end-to-end in validate (§4).
211
+ > `spam`. The guard adds the honeypot on top. Confirm end-to-end in validate (§5).
171
212
 
172
213
  ---
173
214
 
@@ -210,18 +251,42 @@ A user validation error is a **normal UI state, not a build error**. When `conta
210
251
  ## 4 — Email delivery & the `wp_mail` caveat (what to tell the owner)
211
252
 
212
253
  CF7's default form mails `[_site_admin_email]` via `wp_mail()`, so **Hostinger does "set up" basic email
213
- by default** — nothing else to configure for the form to send. Two caveats worth surfacing:
254
+ by default** — nothing else to configure for the form to send. One caveat worth surfacing:
214
255
 
215
256
  - **Deliverability.** `wp_mail` from a shared host can land in spam for external recipients without
216
257
  SPF/DKIM. The most reliable recipient is a **Hostinger mailbox on the same domain**. Keep CF7's admin
217
258
  recipient; if the owner wants a different inbox, point them to a same-domain mailbox.
218
- - **Prove it, don't assume it.** Validate (Step 7) POSTs a throwaway test submission and asserts
219
- `status == "mail_sent"`. A `mail_failed` is a real finding — report it (CF7 is wired, but the mailer
220
- needs attention), don't pass silently.
221
- - **Check the honeypot too.** Send one more throwaway submission with the decoy
222
- (`contact_form.honeypot_field`) **filled** — it must come back `status: "spam"` with **no** mail. If it
223
- returns `mail_sent`, the §2b guard plugin isn't active (re-check its deploy). The normal empty-decoy
224
- submission still returns `mail_sent`, so this costs one extra throwaway email at most.
225
259
 
226
260
  Don't install an SMTP plugin or ask for mail credentials as part of this flow — the default `wp_mail`
227
261
  path is the intended behaviour; SMTP is an owner decision in wp-admin if deliverability needs hardening.
262
+
263
+ ---
264
+
265
+ ## 5 — Validate (Step 7): the two test sends
266
+
267
+ Read from [`../../07-validate/SKILL.md`](../../07-validate/SKILL.md) when `site.json → contact_form.enabled` is true.
268
+
269
+ POST one throwaway test submission (dummy
270
+ name/email/subject/message + CF7's hidden `_wpcf7*` fields — see §3
271
+ above) to `contact_form.feedback_url` and assert the JSON
272
+ `status` is **`mail_sent`**. This is the one place a real send happens, so one test email reaches the
273
+ owner — not several. `mail_failed` is a real finding: surface it to the user (CF7 is wired, but
274
+ `wp_mail` delivery/SPF needs attention — a Hostinger mailbox on the domain is the most reliable
275
+ recipient) and log it as an issue. A `validation_failed` means the test payload didn't match the form's
276
+ fields — fix the field names in `site.json`, not the plugin.
277
+ **Then check the honeypot:** POST a **second** throwaway submission with the same valid fields **plus**
278
+ `contact_form.honeypot_field` **filled**, and assert the `status` is **`spam`** (no mail sent). Keep the
279
+ real fields valid — CF7 validates **before** running the spam filter, so an invalid payload would return
280
+ `validation_failed` and never reach the honeypot check. A `mail_sent` here means the
281
+ `cf7-headless-spamguard` plugin isn't active — surface it and re-check its deploy.
282
+
283
+ ---
284
+
285
+ ## 6 — Handover (Step 9)
286
+
287
+ Read from [`../../09-done/SKILL.md`](../../09-done/SKILL.md) when `site.json → contact_form.enabled` is true.
288
+
289
+ In the handover, tell the owner the contact page is live and enquiries email
290
+ the **WordPress admin address** (via `wp_mail`) — and that for the most reliable delivery that address
291
+ should be a Hostinger mailbox on the domain. If validate reported `mail_failed`, say so plainly instead
292
+ of claiming the form sends.
@@ -5,12 +5,59 @@ a **WooCommerce store** (`site.json → woocommerce.enabled: true`) — a brief
5
5
  `**WordPress + WooCommerce**` (one site: content **and** commerce).
6
6
 
7
7
  **WooCommerce is not a separate backend.** It is the `woocommerce` plugin on a normal headless WordPress
8
- install at `/cms` (installed in the provision step). This cookbook is the authoritative home for the store
8
+ install at `/cms` (installed at provision, §0). This cookbook is the authoritative home for the store
9
9
  data layer: how to **seed and CRUD** products, categories and coupons, and how the **storefront** reads
10
10
  the cart, coupons and checkout.
11
11
 
12
12
  ---
13
13
 
14
+ ## 0 — Provision: install, verify, record `site.json`
15
+
16
+ Read from [`../../03-provision/wordpress/SKILL.md`](../../03-provision/wordpress/SKILL.md) Step 5. This is **join-half** work (needs the live instance): run it once
17
+ `provision.status == "completed"`.
18
+
19
+ 1. **Install + activate WooCommerce** (management MCP, async — poll, never blind-retry):
20
+ - `wordpress_plugins_install { username, software: <install_id>, plugins: ["woocommerce"] }`
21
+ - Poll `wordpress_plugins_list-installed { username, software }` until `woocommerce` shows `active`
22
+ (install + activate can complete together), or activate it with
23
+ `wordpress_plugins_activate { username, software, plugin: "woocommerce" }`.
24
+ - Confirm with `wordpress_plugins_check-if-woo-commerce-is-installed { domain: "<domain>" }`. Allow a
25
+ moment for WooCommerce's installer to create its tables and the Shop/Cart/Checkout pages.
26
+ - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
27
+ succeeded** (seen on both `plugins_install` and `jwt-token`). Treat a 500 as "verify, don't assume":
28
+ poll `list-installed` / re-check before retrying, and never fire a second install blindly.
29
+ 2. **Verify the store endpoints (public, no auth):**
30
+
31
+ | Check | How | Expect |
32
+ |---|---|---|
33
+ | WooCommerce active | `wordpress_plugins_check-if-woo-commerce-is-installed { domain }` | installed + active |
34
+ | Store API answers | `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` | 200 (empty until content-model seeds — fine) |
35
+ | Both namespaces loaded | `GET https://<domain>/cms/wp-json/` → `namespaces` | contains `wc/store/v1` **and** `wc/v3` |
36
+
37
+ Pretty permalinks are on by default on a headless install, so the Store API resolves immediately; if a
38
+ store route ever 404s, the permalink structure is the thing to check.
39
+
40
+ Then add the `woocommerce` block and the store URLs to `site.json` (provision Step 6; `backend` stays
41
+ `"wordpress"`). Checkout stays off until the owner sets it up (§4), so `payment_enabled` starts `false`:
42
+
43
+ ```json
44
+ {
45
+ "woocommerce": {
46
+ "enabled": true,
47
+ "seeded_via": "per-site-wp-mcp",
48
+ "currency": "<currency_code from GET {store_api}/products or the install default>",
49
+ "payment_enabled": false,
50
+ "checkout_setup": "owner enables a payment method + shipping in wp-admin"
51
+ },
52
+ "urls": {
53
+ "store_api": "https://<domain>/cms/wp-json/wc/store/v1",
54
+ "wc_rest_api": "https://<domain>/cms/wp-json/wc/v3"
55
+ }
56
+ }
57
+ ```
58
+
59
+ ---
60
+
14
61
  ## 1 — The one rule: drive the store through the per-site WP MCP
15
62
 
16
63
  There is **no seed plugin, no WP-CLI, and no REST consumer key in this flow**: catalog data goes through
@@ -13,22 +13,15 @@ not a conversation: the frontend step implements `design.md`, not the chat.
13
13
  user gave. **Out:** `~/.hostinger/<domain>/design.md` and the logo files in
14
14
  `~/.hostinger/<domain>/brand/`.
15
15
 
16
- > ## ⚠️ Build mode: "Bring your own frontend"? This step defers to the user
17
- > Read `brief.md` → **Build mode** first. When it is **Bring your own frontend**, the user drives the
18
- > design — **do not generate three directions or write a prescriptive `design.md` over their project.**
19
- > The frontend already exists (or the user vibe-codes it with you); your job is to follow *their*
20
- > direction, not impose one. Skip Steps 1–7 below, *Keep the current look* included, even when
21
- > **Design direction** keeps the look of the app in this folder: their own code already carries it.
22
- > Either write nothing, or capture only what the user explicitly asks for (a short note of their
23
- > stated colours/vibe) so the frontend step has it, then do Step 7's `state.json` update so the flow
24
- > moves on to frontend. The logo and token work here apply only when **Build mode is "Agent designs
25
- > and builds"**.
16
+ > **Build mode "Bring your own frontend"? This step defers to the user.** Read `brief.md` → **Build mode**
17
+ > first. When it is **Bring your own frontend**, follow [`bring-your-own-frontend.md`](bring-your-own-frontend.md) instead of Steps 1–7: no three
18
+ > directions and no prescriptive `design.md` over their project.
26
19
 
27
20
  This is **prepare work**: it runs while provision settles (see *Background provision & the instance
28
21
  barrier* in the top-level `SKILL.md`). Nothing here calls the Hostinger connector or the backend.
29
22
 
30
23
  **Keep it short.** Refine already asked about tone and look; don't ask again. The step asks the user
31
- **one** question: either the keep/change question (Step 1 and *Keep the current look*) or the three
24
+ **one** question: either the keep/change question (Step 1 and `keep-look.md`) or the three
32
25
  directions (Step 4), never both. "You decide" is a valid answer.
33
26
 
34
27
  **Talk like a person, not a designer.** Everything the user reads describes how the site will
@@ -68,45 +61,10 @@ Read `brief.md`, `state.json`, and `content-model.md` if it exists.
68
61
  as normal. The current `design.md` becomes one more signal in Step 2, so carry over what the user
69
62
  wants to keep and move away from the rest.
70
63
  - **The brief says to keep the current look** (*Design direction* says so in the owner's words:
71
- "keep the look we have", "same look, new platform") → follow *Keep the current look* below instead
64
+ "keep the look we have", "same look, new platform") → follow [`keep-look.md`](keep-look.md) instead
72
65
  of Steps 2–6. No three directions and no new logo. A live site, screenshots or a brand guide alone
73
66
  are signals for Step 2, not a request to keep.
74
67
 
75
- ### Keep the current look
76
-
77
- 1. **Read the look from what the brief points at.** A live site: use Step 2's reference-site method
78
- (computed fonts, colours by painted area, the feel), but this site is the owner's own, so take its
79
- logo file as it is (the header `<img>` or inline `<svg>`, plus its favicon if it has one) and save
80
- it unchanged in `brand/`. Screenshots or a brand guide: read the colours and lettering from them;
81
- a logo seen only in a screenshot counts as no logo file, so list "logo file needed" under gaps in
82
- the final report. The app in this folder (the path under `brief.md` → **Existing project**):
83
- read its source; no build or browser needed.
84
- - *Colours:* the theme tokens (Tailwind v4 `@theme`, v3 `tailwind.config.*` `theme`/`theme.extend`,
85
- `:root` custom properties), ranked by how often the code uses them (class names, `var()`), with
86
- the page background and body text taken from the root layout or `body`.
87
- - *Fonts:* theme font tokens, `@fontsource` imports or dependencies, Google Fonts `<link>` or
88
- `@import`, and the `font-family` on `body` and headings.
89
- - *Logo:* files named `logo*` in `public/`, `static/`, `src/assets/` or `assets/`;
90
- `favicon*`, `icon*` or `apple-icon*` in `public/`, `static/`, `app/` or `src/app/`; or the icon
91
- declared by `<link rel="icon">` in `index.html` or the root layout's `metadata.icons`. Copy them
92
- unchanged into `brand/`.
93
-
94
- Files or exact colours and fonts the owner supplied win over anything you read.
95
- 2. **Confirm in one question.** Describe the kept look in two plain sentences and ask: *keep it, or
96
- change something?* "Keep the look we have" still gets this question; skip it only when the brief
97
- says to change nothing at all ("keep it exactly as it is"). A skipped tool result is not Keep; see
98
- *When you ask the user* in the top-level `SKILL.md`. Change →
99
- apply only what they asked for; a request for a new logo runs Step 6 for the logo alone.
100
- 3. **Check it** as in Step 5. The kept colours are fixed like brand colours: a pair that fails gets a
101
- shade of the same hue in that role only. Spacing moves to the nearest grid value, and a font
102
- without an `@fontsource` package swaps to the closest one that resolves (5.4).
103
- 4. **Logo.** Reuse the existing logo and favicon unchanged; never redraw or recolour them. With no
104
- existing logo, the header shows the site name as text in the kept display font; no icon is drawn.
105
- 5. **Write `design.md`** (Step 7) from the kept look, then hand off as usual. In **Logo**:
106
- - *Files* and *Use* name the files as saved (a `.png` stays a `.png`), or say "No favicon kept".
107
- - With no logo: *Files* says "None", *Use* says the header link holds the site name as text in
108
- `--font-display` and the browser's default favicon stays, and the *Don't* line is dropped.
109
-
110
68
  ## Step 2 — Collect the signals
111
69
 
112
70
  Before inventing anything, gather what already constrains the design:
@@ -131,7 +89,7 @@ works, say so in one line and continue from the brief alone. Pull **cues**:
131
89
  - **Feel:** look at the first screen and one further down (screenshots shown to you, not saved in
132
90
  the workspace) and note what creates the feel: type weight, colour blocking, shapes, density.
133
91
 
134
- **Borrow cues, never assets** (the owner's own site under *Keep the current look* is the exception).
92
+ **Borrow cues, never assets** (the owner's own site under `keep-look.md` is the exception).
135
93
  Don't use its logo, copy, images or exact layout. **The brief wins** over the live site when they
136
94
  disagree (the user's words are what they want). Note the mismatch in the direction.
137
95
 
@@ -475,21 +433,6 @@ duotone…); alt text written from what the photo shows.>
475
433
 
476
434
  ## Invariants
477
435
 
478
- - **One question.** Refine owns discovery; this step only chooses among directions (or keeps the
479
- existing look).
480
- - **8-point grid, always.** No spacing, size, radius or breakpoint off the grid except the listed
481
- exemptions.
482
- - **WCAG 2.2 AA is the floor.** No direction is offered, chosen or written that fails it. Brand
483
- colours keep their hue but only appear in roles where they pass.
484
- - **The header never wraps.** Nav labels and the header button stay on one line (`white-space:
485
- nowrap`); the inline nav collapses to a menu button at the width it stops fitting, not only at the
486
- mobile breakpoint (5.5).
487
- - **Brand assets are fixed.** A supplied logo, colour or font appears in every direction, unchanged.
488
- - **The logo is the name plus a simple icon.** The site name as text in the display font beside a
489
- small hand-written SVG icon that is also the favicon, or a supplied or kept logo unchanged. No
490
- emoji or raster clip-art. A kept look with no logo shows the name as text and gets no icon.
491
436
  - **Self-hosted fonts only** (`@fontsource`). No Google Fonts or other font CDN links in the output.
492
437
  - **The tokens block is the only source of values** (breakpoints excepted). Components and pages
493
438
  reference tokens, never raw hex codes, pixel values or font names.
494
- - **No backend calls.** Design never waits on provision and never writes to the instance.
495
- - **Never overwrite an existing `design.md` silently.** Keep or change, as in Step 1.
@@ -0,0 +1,11 @@
1
+ # headless — Build mode "Bring your own frontend" (design)
2
+
3
+ Read from [`SKILL.md`](SKILL.md) when `brief.md` → **Build mode** is **Bring your own frontend**.
4
+
5
+ The user drives the design — **do not generate three directions or write a prescriptive `design.md` over their project.**
6
+ The frontend already exists (or the user vibe-codes it with you); your job is to follow *their*
7
+ direction, not impose one. Skip `SKILL.md` Steps 1–7, `keep-look.md` included, even when
8
+ **Design direction** keeps the look of the app in this folder: their own code already carries it.
9
+ Either write nothing, or capture only what the user explicitly asks for (a short note of their
10
+ stated colours/vibe) so the frontend step has it, then do only the `state.json` update at the end of `SKILL.md` Step 7 so the flow
11
+ moves on to frontend.
@@ -0,0 +1,37 @@
1
+ # headless — Keep the current look (design)
2
+
3
+ Read from [`SKILL.md`](SKILL.md) Step 1 when the brief says to keep the current look. Step numbers
4
+ below are that file's; 5.x are its Step 5 checks.
5
+
6
+ 1. **Read the look from what the brief points at.** A live site: use Step 2's reference-site method
7
+ (computed fonts, colours by painted area, the feel), but this site is the owner's own, so take its
8
+ logo file as it is (the header `<img>` or inline `<svg>`, plus its favicon if it has one) and save
9
+ it unchanged in `brand/`. Screenshots or a brand guide: read the colours and lettering from them;
10
+ a logo seen only in a screenshot counts as no logo file, so list "logo file needed" under gaps in
11
+ the final report. The app in this folder (the path under `brief.md` → **Existing project**):
12
+ read its source; no build or browser needed.
13
+ - *Colours:* the theme tokens (Tailwind v4 `@theme`, v3 `tailwind.config.*` `theme`/`theme.extend`,
14
+ `:root` custom properties), ranked by how often the code uses them (class names, `var()`), with
15
+ the page background and body text taken from the root layout or `body`.
16
+ - *Fonts:* theme font tokens, `@fontsource` imports or dependencies, Google Fonts `<link>` or
17
+ `@import`, and the `font-family` on `body` and headings.
18
+ - *Logo:* files named `logo*` in `public/`, `static/`, `src/assets/` or `assets/`;
19
+ `favicon*`, `icon*` or `apple-icon*` in `public/`, `static/`, `app/` or `src/app/`; or the icon
20
+ declared by `<link rel="icon">` in `index.html` or the root layout's `metadata.icons`. Copy them
21
+ unchanged into `brand/`.
22
+
23
+ Files or exact colours and fonts the owner supplied win over anything you read.
24
+ 2. **Confirm in one question.** Describe the kept look in two plain sentences and ask: *keep it, or
25
+ change something?* "Keep the look we have" still gets this question; skip it only when the brief
26
+ says to change nothing at all ("keep it exactly as it is"). A skipped tool result is not Keep; see
27
+ *When you ask the user* in the top-level `SKILL.md`. Change →
28
+ apply only what they asked for; a request for a new logo runs Step 6 for the logo alone.
29
+ 3. **Check it** as in Step 5. The kept colours are fixed like brand colours: a pair that fails gets a
30
+ shade of the same hue in that role only. Spacing moves to the nearest grid value, and a font
31
+ without an `@fontsource` package swaps to the closest one that resolves (5.4).
32
+ 4. **Logo.** Reuse the existing logo and favicon unchanged; never redraw or recolour them. With no
33
+ existing logo, the header shows the site name as text in the kept display font; no icon is drawn.
34
+ 5. **Write `design.md`** (Step 7) from the kept look, then hand off as usual. In **Logo**:
35
+ - *Files* and *Use* name the files as saved (a `.png` stays a `.png`), or say "No favicon kept".
36
+ - With no logo: *Files* says "None", *Use* says the header link holds the site name as text in
37
+ `--font-display` and the browser's default favicon stays, and the *Don't* line is dropped.
@@ -11,17 +11,9 @@ is where it becomes real code. There's no per-framework recipe — use good judg
11
11
  as the contract, and ask only for the clarifications you genuinely need. **Out:** source in the site
12
12
  workspace `~/.hostinger/<domain>/src/`.
13
13
 
14
- > ## ⚠️ Build mode: "Bring your own frontend"? Read this first (any backend)
15
- > Read `brief.md` → **Build mode**. When it is **Bring your own frontend**, the user already has a
16
- > frontend (the project in the folder the command was run in) and this step **wires it to the backend
17
- > from `site.json` — it does not scaffold a new project and there is usually no `design.md` to
18
- > implement** (the design step deferred to the user). **Use their project as the source**: copy or
19
- > point `~/.hostinger/<domain>/src/` at it, keep its framework and UI, and collaborate on changes at
20
- > the user's direction (vibe-code with them). Your job is to connect it to the live backend (WordPress
21
- > `wp/v2` reads, the WooCommerce/Ecommerce Store API, env/keys) and make it deployable (set
22
- > `engines.node` to `22`, remove any `.htaccess`), then hand off to deploy. This generalises the Webapp
23
- > "existing app" case below to WordPress and Ecommerce too. When **Build mode is "Agent designs and
24
- > builds"**, ignore this box and proceed normally (scaffold + implement `design.md`).
14
+ > **Build mode "Bring your own frontend"? Read this first (any backend).** Read `brief.md` → **Build mode**.
15
+ > When it is **Bring your own frontend**, follow [`bring-your-own-frontend.md`](bring-your-own-frontend.md): wire the user's own project to the
16
+ > backend instead of scaffolding one. When it is **Agent designs and builds**, proceed normally.
25
17
 
26
18
  > ## ⚠️ Webapp backend? Read this first
27
19
  > A `webapp` brief has **no CMS/store and no `content-model.md`** — the app owns its own data (its own
@@ -60,10 +52,7 @@ it, and the backend constraint:
60
52
  - Map rendering → framework: **`ssr` → Next.js**, **`ssg` → Astro** — unless the brief/prompt explicitly
61
53
  names another supported framework, in which case use that.
62
54
 
63
- Supported frameworks (what the Hostinger build pipeline can deploy — the `app_type` in Step 8 deploy):
64
-
65
- - **Server/SSR-capable:** Next.js, Nuxt.js, Astro, SvelteKit, Express, NestJS, Fastify.
66
- - **Static / SPA:** React, Vue, Angular, Vite, Parcel, Preact, Svelte, (Astro / SvelteKit static too).
55
+ Supported frameworks are the ones in deploy's *Build configurations* table (`../08-deploy/SKILL.md`).
67
56
 
68
57
  Confirm the framework with the user in one line only if the brief left it open. Record the choice in
69
58
  `state.json`:
@@ -72,8 +61,7 @@ Confirm the framework with the user in one line only if the brief left it open.
72
61
  { "frontend": { "framework": "nextjs", "rendering": "ssr" } }
73
62
  ```
74
63
 
75
- If the brief is silent, default to **Next.js SSR**. Ecommerce must be SSR (never SSG) — but the SSR
76
- framework itself is free to be any supported one, not just Next.js.
64
+ If the brief is silent, default to **Next.js SSR**.
77
65
 
78
66
  ## Step 2 — Implement `design.md` (don't re-design)
79
67
 
@@ -115,46 +103,17 @@ Read the backend from `site.json`:
115
103
  Leave HTML fields (`content.rendered`, an excerpt shown as HTML) as they are, and never inject a
116
104
  decoded field as raw HTML.
117
105
  - **Contact form** (`site.json → contact_form.enabled: true`, any WordPress backend) → render the
118
- contact page's form and submit it **client-side** to Contact Form 7's public feedback endpoint. Put a
119
- `submitContactForm(data)` helper in the one data module: build a `FormData` with the field names from
120
- `contact_form.fields` (e.g. `your-name`, `your-email`, `your-subject`, `your-message`) **plus CF7's
121
- hidden fields** — `_wpcf7` = `contact_form.form_id`, `_wpcf7_version`, `_wpcf7_locale` (e.g. `en_US`),
122
- `_wpcf7_unit_tag` (any stable string), `_wpcf7_container_post` = `0` — and `POST` it to
123
- `contact_form.feedback_url` **without setting `Content-Type`** (let the browser add the multipart
124
- boundary). `/cms` is same-origin, so no CORS and no secret. Branch on the JSON `status`: `mail_sent`
125
- → success state; `validation_failed` → map `invalid_fields[].field` to per-input errors;
126
- `spam`/`aborted`/`mail_failed` → a generic "couldn't send, try again" message. Include the honeypot
127
- decoy field named in `contact_form.honeypot_field` (e.g. `your_website`), rendered hidden/off-screen,
128
- **empty**, `autocomplete="off"`, `tabindex="-1"` — the deployed spam guard rejects it if filled. A user
129
- validation error is a **normal UI state, not a build error**. When `contact_form.enabled` is `false` or absent, render the contact page with
130
- plain contact details and **no form** — graceful, like disabled checkout; never half-build. Full
131
- contract: `../04-content-model/wordpress/contact-form.md` §3.
106
+ contact page's form and submit it **client-side** to `contact_form.feedback_url` exactly as
107
+ [`../04-content-model/wordpress/contact-form.md`](../04-content-model/wordpress/contact-form.md) §3
108
+ says. When `contact_form.enabled` is `false` or absent, render the contact page with plain contact
109
+ details and **no form** — graceful, like disabled checkout; never half-build.
132
110
  - **WordPress + WooCommerce** (`site.json → woocommerce.enabled: true`) → the WordPress bullet above **plus**
133
- the store. Read the catalog over the **public WooCommerce Store API** (`site.json → urls.store_api`,
134
- `/cms/wp-json/wc/store/v1`, no auth, open CORS): `GET /products` (prices are **integer minor units** on
135
- `prices.price` with `prices.currency_minor_unit` — divide to display), `GET /products/categories`. Cart,
136
- coupons and checkout are **client-side** against the Store API with the `Nonce` + `Cart-Token` headers
137
- (`GET /cart`, `POST /cart/add-item`, `/cart/apply-coupon`, `POST /checkout`) — see
138
- `../04-content-model/wordpress/woocommerce.md`. **Never embed a consumer key client-side**; the
139
- storefront is fully public. Blog/pages on the same site still come from `urls.rest_api` (`wp/v2`) + Yoast.
140
- - **Honour `site.json → woocommerce.payment_enabled`.** It is `false` until the owner enables a payment
141
- gateway + shipping in wp-admin (that config isn't reachable headlessly — see the provision note). While
142
- `false`, build the full catalog, product pages and the client-side cart as normal, but render a
143
- graceful disabled-checkout state (e.g. a disabled "Checkout" with "Checkout isn't set up yet"), **don't
144
- call `/checkout`**, and don't treat it as a build error. When `true`, wire checkout (`payment_method`
145
- `"cod"` works out of the box).
146
- - **Ecommerce** → the **public Hostinger Storefront Core V2 API** (`https://api-ecommerce.hostinger.com/v2`,
147
- no auth, open CORS), keyed on the **custom sales channel** (`site.json → ecommerce.sales_channel.id`):
148
- `GET /channels/<scha_*>/products` (prices are **minor units** on variants), `POST /channels/<scha_*>/checkout`
149
- for buying. Cart is client-side; never embed a token. Read
150
- `ecommerce_miscellaneous_custom-storefront-setup-instructions` for the authoritative, current guide.
151
- - **Honour `site.json → ecommerce.payment_enabled`.** When it is `false` (free account / no paid
152
- Ecommerce plan — see the provision gate), there is **no checkout**: build the full catalog, product
153
- pages and the client-side cart as normal, but **do not call the checkout endpoint**. Instead render
154
- a clear, graceful state at the checkout step — e.g. a disabled "Checkout" button with a short note
155
- like "Online checkout isn't available on this plan yet" (and/or a contact/enquiry fallback). A
156
- missing checkout is **not** a build error here — never leave the storefront half-built, throw, or
157
- retry checkout because payment is off. When `payment_enabled` is `true`, wire checkout normally.
111
+ the store, read over the **public WooCommerce Store API** (`site.json → urls.store_api`): follow
112
+ [`../04-content-model/wordpress/woocommerce.md`](../04-content-model/wordpress/woocommerce.md) §2 for
113
+ the calls, headers and minor-unit prices, and §4 for `site.json → woocommerce.payment_enabled` (while
114
+ `false`, a graceful disabled-checkout state, no `/checkout` call, not a build error). **Never embed a
115
+ consumer key client-side.**
116
+ - **Ecommerce** → the public Hostinger Storefront Core V2 API: follow [`ecommerce.md`](ecommerce.md).
158
117
  - **Webapp** → **no `content-model.md` and no headless backend to read**. The app uses its own data source:
159
118
  the MySQL database from `site.json → database` (through the `DB_*` / `DATABASE_URL` env vars — set at
160
119
  provision/deploy, see `../03-provision/webapp/SKILL.md` Step 3; `127.0.0.1` only resolves on the server,
@@ -0,0 +1,13 @@
1
+ # headless — Build mode "Bring your own frontend" (frontend)
2
+
3
+ Read from [`SKILL.md`](SKILL.md) when `brief.md` → **Build mode** is **Bring your own frontend** (any backend).
4
+
5
+ The user already has a
6
+ frontend (the project in the folder the command was run in) and this step **wires it to the backend
7
+ from `site.json` — it does not scaffold a new project and there is usually no `design.md` to
8
+ implement** (the design step deferred to the user). **Use their project as the source**: copy or
9
+ point `~/.hostinger/<domain>/src/` at it, keep its framework and UI, and collaborate on changes at
10
+ the user's direction (vibe-code with them). Your job is to connect it to the live backend (WordPress
11
+ `wp/v2` reads, the WooCommerce/Ecommerce Store API, env/keys) and make it deployable (set
12
+ `engines.node` to `22`, remove any `.htaccess`), then hand off to deploy. This generalises the Webapp
13
+ "existing app" case in `SKILL.md` to WordPress and Ecommerce too.
@@ -0,0 +1,16 @@
1
+ # headless — Ecommerce storefront (frontend)
2
+
3
+ Read from [`SKILL.md`](SKILL.md) Step 3 when `site.json → backend` is `"ecommerce"`.
4
+
5
+ Ecommerce → the **public Hostinger Storefront Core V2 API** (`https://api-ecommerce.hostinger.com/v2`,
6
+ no auth, open CORS), keyed on the **custom sales channel** (`site.json → ecommerce.sales_channel.id`):
7
+ `GET /channels/<scha_*>/products` (prices are **minor units** on variants), `POST /channels/<scha_*>/checkout`
8
+ for buying. Cart is client-side; never embed a token. Read
9
+ `ecommerce_miscellaneous_custom-storefront-setup-instructions` for the authoritative, current guide.
10
+ - **Honour `site.json → ecommerce.payment_enabled`.** When it is `false` (free account / no paid
11
+ Ecommerce plan — see the provision gate), there is **no checkout**: build the full catalog, product
12
+ pages and the client-side cart as normal, but **do not call the checkout endpoint**. Instead render
13
+ a clear, graceful state at the checkout step — e.g. a disabled "Checkout" button with a short note
14
+ like "Online checkout isn't available on this plan yet" (and/or a contact/enquiry fallback). A
15
+ missing checkout is **not** a build error here — never leave the storefront half-built, throw, or
16
+ retry checkout because payment is off. When `payment_enabled` is `true`, wire checkout normally.
@@ -33,19 +33,9 @@ with an empty catalog means the push didn't land:
33
33
  count matches the plan. Don't test checkout while `woocommerce.payment_enabled` is `false`.
34
34
  - **Ecommerce:** query `urls.storefront_api` for the sales channel → 200 with the seeded products and
35
35
  prices *(confirm against the store)*.
36
- - **Contact form** (`site.json → contact_form.enabled`): POST one throwaway test submission (dummy
37
- name/email/subject/message + CF7's hidden `_wpcf7*` fields — see
38
- `../04-content-model/wordpress/contact-form.md` §3) to `contact_form.feedback_url` and assert the JSON
39
- `status` is **`mail_sent`**. This is the one place a real send happens, so one test email reaches the
40
- owner — not several. `mail_failed` is a real finding: surface it to the user (CF7 is wired, but
41
- `wp_mail` delivery/SPF needs attention — a Hostinger mailbox on the domain is the most reliable
42
- recipient) and log it as an issue. A `validation_failed` means the test payload didn't match the form's
43
- fields — fix the field names in `site.json`, not the plugin.
44
- **Then check the honeypot:** POST a **second** throwaway submission with the same valid fields **plus**
45
- `contact_form.honeypot_field` **filled**, and assert the `status` is **`spam`** (no mail sent). Keep the
46
- real fields valid — CF7 validates **before** running the spam filter, so an invalid payload would return
47
- `validation_failed` and never reach the honeypot check. A `mail_sent` here means the
48
- `cf7-headless-spamguard` plugin isn't active — surface it and re-check its deploy.
36
+ - **Contact form** (`site.json → contact_form.enabled`): send the two throwaway test submissions in
37
+ [`../04-content-model/wordpress/contact-form.md`](../04-content-model/wordpress/contact-form.md) §5: the
38
+ first must return `status` **`mail_sent`**, the one with the honeypot filled **`spam`**.
49
39
 
50
40
  Fail or counts off → fix content-model push before building against live data.
51
41