@hostinger/mcp 3.3.0 → 3.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: headless-step-provision
-description: "Step 3 (provision) of the Hostinger Headless flow. Chooses the backend from brief.md (wordpress | ecommerce | webapp), then routes to the matching subfolder to provision it; writes site.json."
+description: "Step 3 (provision) of the Hostinger Headless flow. Chooses the backend from brief.md (wordpress | ecommerce | webapp), then routes to the matching subfolder to provision it; writes site.json. WordPress + WooCommerce routes to the wordpress subfolder with the WooCommerce store turned on — it is not a separate backend."
 ---
 
 # headless-step-provision
@@ -25,19 +25,74 @@ Read the brief's **Suggested backend** section:
 | Suggested backend | Follow |
 |---|---|
 | WordPress | `wordpress/SKILL.md` |
+| WordPress + WooCommerce | `wordpress/SKILL.md` **with the WooCommerce store on** (see below) |
 | Ecommerce | `ecommerce/SKILL.md` |
 | Webapp | `webapp/SKILL.md` |
 
 If the section is missing or names something else, go back to **refine** — don't pick one here.
 Tell the user the backend and its one-line reason before provisioning.
 
-> **Supported backends: `wordpress`, `ecommerce` and `webapp`.** `webapp` is a plain Node.js app host
-> (an empty website — no CMS, no store, no `/cms`) for any app/SPA that brings its own code and data; it
-> never installs WordPress. PocketBase is not available in this version — refine never proposes it, and
-> there is no `pocketbase/` subfolder; if a brief somehow names it, stop and tell the user rather than
-> improvising it. A **WordPress + Ecommerce** brief has no single combined `start-setup` type yet: stop,
-> tell the user it isn't supported as one site, and offer to continue with just WordPress or just
-> Ecommerce — then route to that one subfolder.
+> **WordPress + WooCommerce is the WordPress backend with a store — not a new backend.** Route it to
+> `wordpress/SKILL.md` and follow that recipe's **optional WooCommerce tail** (install + activate the
+> `woocommerce` plugin and verify the store endpoints; the catalog is seeded later through the per-site WP
+> MCP's native `wc-*` abilities — no custom plugin, no consumer key). `site.json → backend` stays
+> `"wordpress"`; the store is recorded under `site.json → woocommerce` (`enabled: true`). Everything else
+> downstream that routes on
+> `wordpress` (content-model push, deploy's `/cms` preservation, done's wp-admin login) then works
+> unchanged.
+
+> **Supported backends: `wordpress` (optionally with a WooCommerce store), `ecommerce` and `webapp`.**
+> `webapp` is a plain Node.js app host (an empty website — no CMS, no store, no `/cms`) for any app/SPA
+> that brings its own code and data; it never installs WordPress. PocketBase is not available in this
+> version — refine never proposes it, and there is no `pocketbase/` subfolder; if a brief somehow names
+> it, stop and tell the user rather than improvising it. A **WordPress + Ecommerce** brief (two separate
+> backends — a WordPress site **and** a Hostinger Ecommerce store) has no single combined `start-setup`
+> type yet: stop, tell the user it isn't supported as one site, and offer either to continue with just
+> WordPress or just Ecommerce (route to that one subfolder), **or**, if they want content and a store on
+> **one** site, to switch the brief to **WordPress + WooCommerce** — the one-site path, which routes to
+> `wordpress/SKILL.md` with the store on.
+
+## Onboarding handoff — swap an existing empty headless shell (do this before creating anything)
+
+Onboarding can create the website **before** you ever run, then paste the build prompt into this agent.
+When it does, the domain already has an **empty headless shell**: a website set up with
+`hosting_websites_start-setup { type: "headless_empty" }` — `website_type` is `headless`, but **nothing
+is installed** (no WordPress at `/cms`, no store). It is the hosting slot only, waiting for a backend.
+
+So provision has **two entry shapes**, and each subfolder's *detect* step picks between them:
+
+- **An empty headless shell already exists for the domain → adopt it and *swap* it to the chosen
+  backend. Never call `start-setup` again, never create a second site.** The swap is backend-specific:
+  - **WordPress** → install WordPress **into the existing shell's `/cms`** with
+    `wordpress_installations_install { type: "headless" }` (it rewrites the root `.htaccess` and marks
+    the site headless-WordPress). Do **not** use `start-setup { type: "headless_wordpress" }` — that is
+    only for creating a fresh site.
+  - **Ecommerce** → the empty headless shell **is** the storefront host already (a `headless_ecommerce`
+    website installs no store engine either). Adopt it as the frontend host and go straight to creating
+    the store + custom sales channel.
+- **No site exists for the domain at all → create it fresh, exactly as each subfolder defines today**
+  (`start-setup` with the backend's own `type`).
+
+> **Webapp is not part of this handoff at all.** `webapp` is **not** reached on the usual onboarding
+> flow — it is only triggered by experimental actions — so it **ignores headless instances entirely**:
+> it never detects, adopts or swaps an empty headless shell, and provisions its own **Node.js app host**
+> exactly as `webapp/SKILL.md` defines today. The swap below is **WordPress and Ecommerce only**.
+
+**How to tell an empty shell from an already-provisioned backend** (both read `website_type: headless`):
+
+1. Exact-match the domain row in `hosting_websites_list` — if there is **no** row, nothing exists → create fresh.
+2. Within 24 h of onboarding, `hosting_websites_list-setups` still shows the setup `type`
+   (`headless_empty` = empty shell; `headless_wordpress` = WordPress already; `headless_ecommerce` = an
+   ecommerce host). Beyond 24 h the setup drops off — fall back to the backend probe:
+3. `wordpress_installations_list { username, domain, ownership: "all" }` — a row with `directory: "cms"`
+   and `is_valid: true` means WordPress is **already** installed (adopt, don't swap); **no** such row on
+   a `headless` site means the shell is still empty and WordPress must be swapped in. A local `site.json`
+   with a recorded backend means a previous run already provisioned — trust reality over it, but it tells
+   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
+asynchronous — fire it, record `provision.in_progress`, and join at the barrier just like a fresh create.
 
 ## Step 2 — Fire (don't block)
 

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

@@ -48,13 +48,22 @@ 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.
-2. Create (only if absent): `hosting_websites_start-setup { order_id, type: "headless_ecommerce", domain }`
+   → adopt. `running` → poll. `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_start-setup { order_id, type: "headless_ecommerce", domain }`
    — **omit `domain`** for a temporary subdomain: the setup generates one itself (don't call a separate
    subdomain op first — passing a generated free subdomain back as `domain` 422s). The response carries
    the generated domain; if it differs from the workspace dir, move `~/.hostinger/<old>/` → `<new>/` and
    update `brief.md`. Poll `list-setups` to `completed`. `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 —
+> typically created in onboarding), **adopt it as the storefront host and skip the create.** A
+> `headless_ecommerce` website installs no store engine either, so an empty headless shell *is* the host
+> you need — there is no backend to "swap" on the website side. Record its `username`/`order_id` and go
+> straight to Step 2 (store + custom sales channel). Never call `start-setup` on a domain that already
+> has a site.
+
 > Don't expect `/cms` or any API on this domain — it serves the storefront you build (Step 6) and
 > deploy (Step 8).
 

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

@@ -9,27 +9,43 @@ Create the headless WordPress backend for `<domain>` and prove it is ready. One
 every headless site out identically: WordPress in `public_html/cms`, Hostinger AI Assistant + MCP
 adapter, site marked `headless`. **Out:** `site.json`.
 
+> **WordPress + WooCommerce?** This same recipe serves it. When the brief's **Suggested backend** is
+> `**WordPress + WooCommerce**`, provision the WordPress site exactly as below, then run the **optional
+> WooCommerce tail in Step 5** (install + activate the `woocommerce` plugin and verify the store
+> endpoints; the catalog is seeded in content-model via the per-site WP MCP).
+> WooCommerce is a plugin on this WordPress install, **not** a separate backend: `site.json → backend`
+> stays `"wordpress"` and the store is recorded under `site.json → woocommerce`. For a plain WordPress
+> brief, skip Step 5 entirely.
+
 All operations below go through the Hostinger connector (`execute`).
 
-> **Fire vs join (background provision).** Steps 1–2 up to `hosting_websites_start-setup` are the
-> **fire** half: after the setup is queued, record `provision.in_progress` and return to do prepare
-> work (see the router `../SKILL.md`). The readiness **poll** at the end of Step 2, plus Steps 3–4,
-> are the **join** half — run them when an instance-barrier step needs the backend (or immediately, if
-> the agent can't interleave). An already-`completed` site detected in Step 1 means provision is
-> already done: record `provision.completed` and adopt it.
+> **Fire vs join (background provision).** Step 1, plus the queuing call — `hosting_websites_start-setup`
+> for a fresh site (Step 2) **or** `wordpress_installations_install` to swap an empty headless shell
+> (Step 2b) — are the **fire** half: once the job is queued, record `provision.in_progress` and return
+> to do prepare work (see the router `../SKILL.md`). The readiness **poll** at the end of Step 2 / 2b,
+> plus Steps 3–6, are the **join** half — run them when an instance-barrier step needs the backend (or
+> immediately, if the agent can't interleave). An already-`completed` site with WordPress at `/cms`
+> detected in Step 1 means provision is already done: record `provision.completed` and adopt it.
 
 ## Step 1 — Detect before you create (never provision twice)
 
 1. `hosting_websites_list { "domain": "<domain>" }` — substring filter, so **exact-match** the row's
    `domain`. If a row exists, note `username`, `order_id`, `website_type`.
-2. `hosting_websites_list-setups { "domain": "<domain>" }` — exact-match the row:
-   - `completed` → already provisioned → skip to Step 3 (adopt it).
-   - `running` → skip to Step 2 (poll).
-   - `failed` → tell the user and point them at hPanel; do **not** call start-setup again on your own.
-3. If the site exists but `website_type` is not `headless`, stop and tell the user — this domain
-   already hosts a different kind of site.
-
-## Step 2 — Create (only when nothing exists)
+2. **No exact row** → nothing exists on this domain → **create fresh** (Step 2).
+3. **A row exists.** If `website_type` is **not** `headless`, stop and tell the user — this domain
+   already hosts a different kind of site (plain WordPress, Node.js, builder, …); never overwrite it.
+   If it **is** `headless`, work out whether WordPress is already installed or the shell is still empty
+   (see the router's *Onboarding handoff*): check `hosting_websites_list-setups { "domain": "<domain>" }`
+   (exact row) and `wordpress_installations_list { username, domain, ownership: "all" }` (exact row):
+   - Setup `running` → provisioning is underway → skip to Step 2's poll.
+   - Setup `failed` → tell the user and point them at hPanel; do **not** call start-setup again yourself.
+   - A WordPress install with `directory: "cms"` already present (or setup `type: headless_wordpress`)
+     → **already provisioned** → skip to Step 3 (adopt it).
+   - A `headless` site with **no** `/cms` install (an **empty headless shell** — setup
+     `type: headless_empty`, typically from onboarding) → **swap it to WordPress** (Step 2b). Do **not**
+     call `start-setup` again — the website already exists; you only install WordPress into it.
+
+## Step 2 — Create a fresh headless WordPress site (only when no site exists)
 
 1. Pick the plan: `hosting_orders_list { "statuses": ["active"] }`. One active order → use it; several
    → ask the user which.
@@ -50,6 +66,38 @@ All operations below go through the Hostinger connector (`execute`).
 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.
 
+## Step 2b — Swap an empty headless shell to WordPress (only when onboarding already made the shell)
+
+The website already exists as an empty `headless` shell, so there is **no `start-setup`** here — you
+install WordPress straight into its `/cms` directory. This is the onboarding handoff path.
+
+1. Use the shell's `username` and `order_id` from Step 1's row — no new order pick, no new website.
+2. Install WordPress into `/cms`, flagged headless:
+
+   ```json
+   { "operation": "wordpress_installations_install",
+     "params": { "username": "<username>", "domain": "<domain>", "type": "headless",
+       "site_title": "<site title from brief.md>",
+       "credentials": { "login": "<admin login>", "email": "<account email>",
+         "password": "<strong generated password>" } } }
+   ```
+
+   - `type: "headless"` installs into `/cms` with the Hostinger headless MU plugin and marks the site
+     headless-WordPress; **`directory` is not allowed with it** (it is always `cms`). The target must
+     already be `headless` — the headless install rewrites the root `.htaccess`, so the API rejects it
+     with `422` on any non-headless site (which is why Step 1 confirms `website_type: headless` first).
+   - **You generate the admin password** (strong, 8–50 chars, mixed case + a digit) — never ask the user
+     for one and never print it. The user signs in later through a one-click login link (Step 6), so the
+     password only has to exist, not be remembered.
+   - 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.
+
 ## Step 3 — Verify (all must pass)
 
 | Check | How | Expect |
@@ -71,7 +119,78 @@ Notes:
 
 If a check fails: retry once after ~30 s; if it still fails, stop and point the user at hPanel.
 
-## Step 4 — Record `site.json`
+## Step 4 — SEO plugin (Yoast) *(every WordPress site — on by default)*
+
+Every headless WordPress site gets **Yoast SEO** (`wordpress-seo`) installed and activated by default,
+so per-page title/description/Open Graph/JSON-LD come from a maintained plugin's `yoast_head_json`
+rather than being hand-generated from each item's content by the frontend. This is **join-half** work
+(needs the live `/cms` install), so run it once `provision.status == "completed"`, the same way as the
+WooCommerce tail. Tell the user in one line that SEO (Yoast) is being set up; if they explicitly don't
+want it, skip this step and record `seo.enabled: false` — but the default is to install it.
+
+1. **Install + activate Yoast** (management MCP, async — poll, never blind-retry):
+   - `wordpress_plugins_install { username, software: <install_id>, plugins: ["wordpress-seo"] }`
+   - Poll `wordpress_plugins_list-installed { username, software }` until `wordpress-seo` shows
+     `active` (install + activate can complete together), or activate it with
+     `wordpress_plugins_activate { username, software, plugin: "wordpress-seo" }`.
+   - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
+     succeeded**. Treat a 500 as "verify, don't assume": poll `list-installed` before retrying, and
+     never fire a second install blindly.
+2. **Verify** `GET https://<domain>/cms/wp-json/` → `namespaces` once more, and that a sample post/page
+   response carries `yoast_head_json`. The per-item Yoast meta (focus title/description per post) is set
+   later in the **content-model push** — provision only installs + activates the plugin here. Don't fail
+   provision over SEO: if the install can't be confirmed after one retry, record `seo.enabled: false`,
+   tell the user, and let the frontend fall back to generating tags from content.
+
+## Step 5 — WooCommerce store *(only for a `WordPress + WooCommerce` brief — skip otherwise)*
+
+Run this only when the brief's **Suggested backend** is `**WordPress + WooCommerce**`. It turns the
+headless WordPress site into a headless **store**: WooCommerce is the `woocommerce` plugin on this same
+`/cms` install — **not a separate backend**. This is **join-half** work (needs the live instance), so run
+it once `provision.status == "completed"`. The authoritative data-layer reference is
+[`../../04-content-model/wordpress/woocommerce.md`](../../04-content-model/wordpress/woocommerce.md).
+
+> **No custom plugin — the catalog is driven through the per-site WP MCP.** A custom plugin can't be
+> installed into a headless `/cms` from a coding agent, so there is **no seed/config plugin and no REST
+> consumer key in this flow.** Instead, the Hostinger AI Assistant (the per-site WP MCP, same JWT session
+> content-model uses) exposes **native WooCommerce abilities** — `wc-products-*`, `wc-product-categories-*`,
+> `wc-coupons-*`, `wc-orders-*`, `media-upload-from-url`, `wp-settings-*`. Provision just **installs
+> WooCommerce and verifies the store endpoints**; the catalog + coupons are seeded in the content-model
+> push through those abilities (see the cookbook).
+
+1. **Install + activate WooCommerce** (management MCP, async — poll, never blind-retry):
+   - `wordpress_plugins_install { username, software: <install_id>, plugins: ["woocommerce"] }`
+   - Poll `wordpress_plugins_list-installed { username, software }` until `woocommerce` shows `active`
+     (install + activate can complete together), or activate it with
+     `wordpress_plugins_activate { username, software, plugin: "woocommerce" }`.
+   - Confirm with `wordpress_plugins_check-if-woo-commerce-is-installed { domain: "<domain>" }`. Allow a
+     moment for WooCommerce's installer to create its tables and the Shop/Cart/Checkout pages.
+   - **Known quirk:** the `hostinger-wordpress` MCP sometimes returns **HTTP 500 even though the job
+     succeeded** (seen on both `plugins_install` and `jwt-token`). Treat a 500 as "verify, don't assume":
+     poll `list-installed` / re-check before retrying, and never fire a second install blindly.
+2. **Verify the store endpoints (public, no auth):**
+
+   | Check | How | Expect |
+   |---|---|---|
+   | WooCommerce active | `wordpress_plugins_check-if-woo-commerce-is-installed { domain }` | installed + active |
+   | Store API answers | `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` | 200 (empty until content-model seeds — fine) |
+   | Both namespaces loaded | `GET https://<domain>/cms/wp-json/` → `namespaces` | contains `wc/store/v1` **and** `wc/v3` |
+
+   Pretty permalinks are on by default on a headless install, so the Store API resolves immediately; if a
+   store route ever 404s, the permalink structure is the thing to check.
+
+> **Checkout needs owner setup — treat it like the Ecommerce payment gate.** A fresh WooCommerce install
+> has **no payment gateway and no shipping zone enabled**, and that configuration is **not reachable from
+> the headless tooling** (there is no payment/shipping MCP ability, and `wp-settings-update` only writes
+> standard WP settings). So **checkout is unavailable until the owner enables a payment method + shipping
+> in wp-admin** (hand them the one-click login in Step 6). Record `woocommerce.payment_enabled: false`
+> accordingly. This is **not a build failure**: the catalog, product pages, client-side cart and coupon
+> application all work headlessly — the downstream frontend renders a graceful disabled-checkout state and
+> never calls `/checkout` while `payment_enabled` is `false` (see content-model + frontend). Never ask the
+> user for payment credentials. Store currency and address (`woocommerce_*` options) likewise aren't
+> settable headlessly — they follow the install default and the owner can change them in wp-admin.
+
+## Step 6 — Record `site.json`
 
 ```json
 {
@@ -84,6 +203,10 @@ If a check fails: retry once after ~30 s; if it still fails, stop and point the
     "directory": "cms",
     "admin_login": "…"
   },
+  "seo": {
+    "plugin": "wordpress-seo",
+    "enabled": true
+  },
   "urls": {
     "site": "https://<domain>",
     "cms": "https://<domain>/cms",
@@ -98,3 +221,29 @@ If a check fails: retry once after ~30 s; if it still fails, stop and point the
 
 No passwords or tokens in `site.json`. When the user needs wp-admin, mint a one-click link with
 `wordpress_login_create-links { username, software: <install_id> }` — never hand over a password.
+
+**For a `WordPress + WooCommerce` brief, also add a `woocommerce` block and the store URLs** (the
+`backend` field still stays `"wordpress"`):
+
+```json
+{
+  "woocommerce": {
+    "enabled": true,
+    "seeded_via": "per-site-wp-mcp",
+    "currency": "<currency_code from GET {store_api}/products or the install default>",
+    "payment_enabled": false,
+    "checkout_setup": "owner enables a payment method + shipping in wp-admin"
+  },
+  "urls": {
+    "store_api": "https://<domain>/cms/wp-json/wc/store/v1",
+    "wc_rest_api": "https://<domain>/cms/wp-json/wc/v3"
+  }
+}
+```
+
+`rest_api` stays `wp/v2` (the WordPress content contract, for the blog/pages on the same site);
+`store_api` is the public storefront surface (browse/cart/coupons/checkout, no auth). `wc_rest_api`
+(`wc/v3`) is recorded only as the surface the **owner's own** integrations use with a consumer key they
+generate in wp-admin — **this flow never creates or stores a key** (the catalog is seeded through the
+per-site WP MCP's `wc-*` abilities; the storefront uses the public Store API). `payment_enabled` starts
+`false` and flips to `true` only once a gateway + shipping are configured — no secrets in `site.json`.

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

@@ -53,15 +53,18 @@ and tone:
 ## Articles (optional)
 > Generate <N> articles across the brief's categories (<list them>). For each: title, slug,
 > body in the brief's tone, category, any relationship (e.g. destination), published date, SEO,
-> and a featured image (generated into media/, or sourced from Unsplash — see *Images* below) with
+> and a featured image (see *Images* below — Hostinger AI generation or Unsplash stock) with
 > alt text. Omit if the brief has no article-like content.
 
 ## Products (optional — required for a commerce brief)
 > Skip for a non-commerce brief. For a commerce brief, generate the catalog content here (prepare
 > work, no instance): for each product — name, slug, SKU, short + long description in the brief's
-> tone, price, the collection it belongs to, variants if any, and a product image (generated into
-> media/, or sourced from Unsplash — see *Images*) with alt text. Group products into the collections
-> the brief implies. The `ecommerce` push phase creates these on the store's sales channel.
+> tone, price, the collection it belongs to, variants if any, and a product image (see *Images* —
+> Hostinger AI generation or Unsplash stock) with alt text. Group products into the collections
+> the brief implies, and generate any **coupons** the brief calls for (code, type, amount). The
+> `ecommerce` push phase creates these on the store's sales channel; a **WordPress + WooCommerce** brief
+> seeds them into WooCommerce instead (see `wordpress/SKILL.md` + `wordpress/woocommerce.md`) — there
+> the **SKU is the idempotency key** and coupons + product categories are part of the catalog.
 ```
 
 Guidance:
@@ -69,10 +72,12 @@ Guidance:
 - **Fixed vs. prompt.** Title and Description are concrete values. Navigation, Pages and Articles are
   prompts because their volume/wording is generated — keep them as prompts so the push phase (or a
   rerun) can regenerate consistently.
-- **Run the prompts now.** Generate the actual page copy, article drafts and images during the wait —
-  this is the slowest work and the whole reason it runs in parallel. Put generated media in
-  `~/.hostinger/<domain>/media/` and reference it by filename. Record Unsplash images by URL (see
-  *Images* below). Record alt text for every image.
+- **Run the prompts now.** Generate the actual page copy and article drafts during the wait — this is
+  the slowest work and the whole reason it runs in parallel. Images depend on the chosen source (see
+  *Images* below): Unsplash photos and your own generated files can be produced now; Hostinger AI
+  images only generate once the instance exists, so write their brief now and generate at the barrier.
+  Put any generated/own media in `~/.hostinger/<domain>/media/` and reference it by filename. Record
+  alt text for every image.
 - **Optional sections.** Drop **Articles** if the brief has no article-like content. Drop **Products**
   for a non-commerce brief; for a commerce brief, generate the product catalog here (names, prices,
   descriptions, collections, images) — that's prepare work, and the `ecommerce` push phase then creates
@@ -81,12 +86,82 @@ Guidance:
   provision wait, so never wait for it here. If `design.md` already exists when you source images,
   follow its **Imagery** section; otherwise generate neutral, on-topic imagery from the brief.
 
-### Images — source from Unsplash when you can't generate them
+### Images — generate with Hostinger AI, or source stock from Unsplash
+
+Every article (and every product) needs an image. There are two sources, and **you MUST offer the user
+both and let them choose — never pick silently.** State the default for this backend in one line, name
+the other option, and proceed on their answer (a skipped answer / "you decide" = use the default):
+
+| 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 / web search | 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
+> is only correct when **the user chose it**, or when **AI generation actually failed** (and then you say
+> so). Taking stock because it is faster, synchronous, or avoids the async poll is a **defect**, not a
+> shortcut: the async start → poll → upload-before-expiry flow (Option A below) is the expected work, not
+> an optional extra. If you are tempted to skip it "for speed", stop and offer the user the choice instead.
+
+If you can generate images yourself (some agents can), that's a third path: put the files in `media/`
+and record alt text — no tool needed. **Record alt text for every image whichever source you use.**
+
+**During the prepare wait, write an image brief for each image** into `content-model.md` no matter the
+option (subject, `image_type`, aspect, and the alt text you expect). Option B can also *fetch* the
+photo now (below); Option A only generates once the instance exists, so its briefs wait for the barrier.
+
+#### Option A — Hostinger AI image generation (WordPress backends)
+
+`wordpress_ai-content_generate-images` generates on-brand images for a live WordPress install, so it
+runs **at the instance barrier** (after `provision.status == "completed"`), using the install from
+`site.json` (`username`, and `wordpress.install_id` → the `software` path param). Follow `design.md`'s
+**Imagery** section for look and palette. It is **asynchronous**:
+
+1. **Start** one generation per image:
+
+   ```json
+   { "operation": "wordpress_ai-content_generate-images",
+     "params": {
+       "username": "<site.json username>",
+       "software": "<site.json wordpress.install_id>",
+       "prompt": "<what the image shows; for a logo, the wordmark + mark to render>",
+       "image_type": "hero|background|inline|gallery|product|logo",
+       "num_of_images": 1,
+       "style": "<photographic style tokens from design.md; ignored for logo>",
+       "color_guidance": "<logo only — colour direction, not rendered as text>" } }
+   ```
+
+   `prompt` (3–2500 chars) and `image_type` are required; `width`/`height` (128–2048) default per type
+   and are ignored for `logo`. Returns `202` with a `generation_id` and `status: in-progress`.
+   **Only one generation runs per install at a time** — a `409` means one is already running (and it
+   returns no id), so wait for it to finish before starting the next. The endpoint allows 10
+   requests/minute.
+
+2. **Poll** `wordpress_ai-content_generation-result` with `{ username, software, generation_id }`
+   every few seconds until `status` is `completed` (or `failed`). A completed result carries
+   `result.images[]` — each with a **temporary** `url`, plus `width`, `height`, `content_type` — and
+   `result.expires_at`.
+
+3. **Use the images before they expire.** The URLs are short-lived, so in the push phase hand each
+   `url` straight to WordPress with `media-upload-from-url`, which downloads and stores WP's own copy
+   (see the wordpress push `SKILL.md`). Don't persist the temporary URL as the live image. There is no
+   photographer to credit — leave `caption` empty or a short on-brand one. Record under the
+   article/product in `content-model.md`:
+
+   ```markdown
+   Image: Hostinger AI (image_type: <type>, generation_id: <uuid>)
+   Image alt: <what the image shows>
+   Image file: <site>-<subject>.jpg
+   ```
+
+   On `failed`, retry once with a tightened prompt; if it fails again, fall back to Option B and note
+   the gap. Never block the whole push on a single image.
+
+#### Option B — stock photos from Unsplash (any backend, no instance)
 
-Every article needs a featured image. If you can generate images, put them in `media/`. If you
-can't (most coding agents can't), source real photos from Unsplash. This is still prepare work and
-needs no live backend: you only pick the photos and record their URLs here. The push phase uploads
-them.
+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:
@@ -134,13 +209,16 @@ token) to create the menu, pages, posts, categories and media:
 | Suggested backend | Follow |
 |---|---|
 | WordPress | `wordpress/SKILL.md` |
+| WordPress + WooCommerce | `wordpress/SKILL.md` — pushes WP content **and** seeds the WooCommerce catalog (its WooCommerce section + `wordpress/woocommerce.md`) |
 | Ecommerce | `ecommerce/SKILL.md` |
 | Webapp | — (no push; skip to frontend) |
 
-> **Supported backends: `wordpress`, `ecommerce`, and `webapp`** — where `webapp` is "supported" by
-> **skipping this whole stage** (it has no content backend; see the note below). PocketBase is not
-> available in this version. Push to whichever single backend provision set up (see the provision
-> router) — don't try to push to two backends here.
+> **Supported backends: `wordpress` (optionally with a WooCommerce store), `ecommerce`, and `webapp`** —
+> where `webapp` is "supported" by **skipping this whole stage** (it has no content backend; see the note
+> below). A **WordPress + WooCommerce** brief routes to `wordpress/SKILL.md`, which pushes the WP content
+> **and** seeds the WooCommerce catalog in the same push. PocketBase is not available in this version.
+> Push to whichever single backend provision set up (see the provision router) — don't try to push to two
+> backends here.
 >
 > **Webapp has no content backend.** There is no CMS or store to seed, so a `webapp` brief **skips this
 > whole stage** — both prepare and push. The app owns its own data (its own API or database). Leave

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

@@ -29,9 +29,17 @@ authenticated; the admin user context (`wp_set_current_user`) exists only *insid
 | **Per-site WP MCP** | `urls.wp_mcp` (`mcp_url`) | **all writes** — create content through its ability tools |
 | **WP REST API** `wp/v2` | `urls.rest_api` | **public reads only** (no auth needed) — what the Step 6 frontend consumes; do not write to it with the JWT |
 
-> **The WordPress content model is posts, pages and categories** (plus media). For **SEO**, install
-> **Yoast** through the connector so meta + schema come from a maintained plugin; the frontend reads each
-> item's `yoast_head_json` (Step 4.7 below).
+> **The WordPress content model is posts, pages and categories** (plus media). For **SEO**, **Yoast**
+> is already installed + activated at provision (every headless WordPress site — see provision Step 4),
+> so meta + schema come from a maintained plugin and the frontend reads each item's `yoast_head_json`.
+> This push only sets per-item Yoast meta (Step 4.7 below).
+
+> **A store on this site? See [`woocommerce.md`](woocommerce.md).** When the brief's **Suggested
+> backend** is `**WordPress + WooCommerce**` (`site.json → woocommerce.enabled: true`), this push also
+> seeds the WooCommerce catalog — products, categories and coupons — through the **same per-site WP MCP
+> session**, which exposes native `wc-products-*`, `wc-product-categories-*` and `wc-coupons-*` abilities
+> (no custom plugin, no consumer key). Do the WordPress content below as normal, then run the **WooCommerce
+> catalog** section before you hand off.
 
 ## Step 1 — Open the authenticated MCP session
 
@@ -76,7 +84,10 @@ Seen on a live install (Hostinger AI Assistant, discovery mode): the meta-tools
 `hostinger-ai-execute-ability { name, parameters }`. The abilities are named
 `hostinger-ai/<thing>-<action>`, e.g. `posts-create`, `posts-update`, `media-upload-from-url`,
 `media-delete`. Call `get-ability-info` for each schema before using it. Results come back as
-`{ ability, result: { data, … } }` for lists and `{ ability, result: {…} }` for single objects.
+`{ ability, result: { data, … } }` for lists and `{ ability, result: {…} }` for single objects — so a
+create answers **`200`** (not `201`) and the new object's `id` is **inside** `result` (`result.id`, or
+`result.data.id`), never at the top level. A missing top-level `id` is not a failure; read it from
+`result`.
 
 ## Step 3 — Idempotency rule (makes resume safe)
 
@@ -96,29 +107,41 @@ reuse its `id`; empty → create. Capture each returned `id` and record the id m
 1. **Site Title & Description** (the helper's global part) → the Settings ability.
 2. **Categories / tags** — one per term in the helper → Categories / Tags abilities. Keep `name → id`.
 3. **Media.** Upload every image in the helper, set `alt_text`, and keep `filename → id`. See
-   *Media upload* below for both sources: a generated file in `media/`, or an Unsplash URL.
-4. **Pages** — each static/index page → Pages ability (`title`, `slug`, block/HTML `content`,
-   `status: publish`). Keep `slug → id`.
-5. **Posts (articles)** — each → Posts ability (`title`, `slug`, `content`, `status: publish`,
-   `categories: [id]`, `tags: [id…]`, `featured_media: <id>`, `date`). (The plugin block-converts post
-   content on insert via `rest_pre_insert_post`, so HTML bodies are fine.)
+   *Media upload* below for all sources: a Hostinger-AI image URL, an Unsplash URL, or a generated
+   file in `media/`. For a Hostinger-AI image, generate it now (its URL is temporary — see the
+   content-model `SKILL.md`, *Images* Option A) and upload straight away, before `expires_at`.
+4. **Pages** — each static/index page → Pages ability. Pass `title`, `content` and `excerpt` as
+   **`{ "raw": "…" }` objects** (see the note below), plus `slug`, `status: publish`. Keep `slug → id`.
+5. **Posts (articles)** — each → Posts ability: `title`, `content` and `excerpt` as **`{ "raw": "…" }`**
+   (note below), plus `slug`, `status: publish`, `categories: [id]`, `tags: [id…]`,
+   `featured_media: <id>`, `date`. (The plugin block-converts post content on insert via
+   `rest_pre_insert_post`, so HTML bodies in `content.raw` are fine.)
+
+   > **Create payload gotcha (`pages-create` / `posts-create`).** These abilities take `title`,
+   > `content` and `excerpt` as WordPress's core **`{ "raw": "…" }` objects**, not bare strings. Pass a
+   > bare string and the field is silently dropped — the create still answers `200`, so you get a
+   > *published-but-empty* page or post with nothing to key off. Always send `{ "raw": "…" }` and
+   > read the new `id` from `result` (see Step 2). Confirm the exact field shape with
+   > `get-ability-info` if a schema differs.
 6. **Navigation** — Menus / Navigation abilities: create the menu, then an item per nav entry
    referencing a page `id` (or a custom URL for listing routes). **Headless note:** the Step 6
    frontend renders nav from `content-model.md`, so the WP menu is for owners editing in wp-admin, not
    what the live site reads — create it, but it isn't the source of truth.
-7. **SEO** — prefer **Yoast SEO**, installed through the connector:
-   `wordpress_plugins_install { username, software, plugins: ["wordpress-seo"] }` (async), poll
-   `wordpress_plugins_list-installed { username, software }` until `wordpress-seo` appears, then
-   `wordpress_plugins_activate { username, software, plugin: "wordpress-seo" }`. It generates meta +
-   schema, and the frontend reads `yoast_head_json` per post/page. Set each post's Yoast
-   title/description if an ability exposes it; otherwise the excerpt + title are a fine fallback. Don't
-   fail the push over SEO fields.
+7. **SEO** — **Yoast SEO** (`wordpress-seo`) is already installed + activated at provision (Step 4 of
+   the WordPress provision recipe), so it generates meta + schema and the frontend reads
+   `yoast_head_json` per post/page. Here, just set each post's Yoast title/description if an ability
+   exposes it; otherwise the excerpt + title are a fine fallback. Don't fail the push over SEO fields.
+   If `site.json → seo.enabled` is `false` (the owner declined Yoast, or provision couldn't confirm the
+   install), skip this and let the frontend generate tags from content — don't try to install the
+   plugin from the content stage.
 
 ### Media upload
 
-**From a URL (Unsplash or any direct file URL).** Use `hostinger-ai/media-upload-from-url`.
-WordPress downloads the file and stores its own copy, so the site never depends on the external URL
-staying up:
+**From a URL (a Hostinger-AI image, Unsplash, or any direct file URL).** Use
+`hostinger-ai/media-upload-from-url`. WordPress downloads the file and stores its own copy, so the
+site never depends on the external URL staying up — which is exactly why a **Hostinger-AI** image
+(whose `url` from `wordpress_ai-content_generation-result` is temporary) must be uploaded here, while
+it is still valid; drop the Unsplash-only `caption`/`description` for AI images:
 
 ```json
 { "name": "hostinger-ai/media-upload-from-url",
@@ -171,8 +194,30 @@ duplicates with `media-delete { id, force: true }`.
   → id) so the frontend data phase and any re-run resolve references directly. Include one row per
   media item: filename, credit and source page, the post it's featured on, and its id.
 
+## WooCommerce catalog *(only for a `WordPress + WooCommerce` brief — skip otherwise)*
+
+When `site.json → woocommerce.enabled` is `true`, also seed the store **in this same authenticated MCP
+session**, using WooCommerce abilities the Assistant exposes alongside the content ones. Full recipe (incl.
+the storefront Store API and the checkout gate): [`woocommerce.md`](woocommerce.md). In short:
+
+1. **Product categories** — `wc-product-categories-list` (reuse by slug/name) else
+   `wc-product-categories-create { name, slug }`. Keep `name → id`.
+2. **Products** — **idempotent by SKU**: `wc-products-search { sku }` → reuse, else
+   `wc-products-create { name, type:"simple", sku, regular_price:"<decimal>", description, status:"publish",
+   categories:[{id}] }`. For images, `media-upload-from-url` then `wc-products-update { id, images:[{id}] }`.
+3. **Coupons** — **idempotent by code**: `wc-coupons-search { code }` → reuse, else
+   `wc-coupons-create { code, discount_type, amount }`.
+4. **Verify over the public Store API** (no auth): `GET {urls.store_api}/products?per_page=100` count +
+   `prices` (minor units), `GET {urls.store_api}/products/categories`. Record the SKU→id map, category ids
+   and coupon codes into `content-model.md` under `## Created in WooCommerce`.
+
+> **Don't seed or test checkout here.** A fresh WooCommerce install has no payment gateway/shipping and
+> that config isn't reachable headlessly (`site.json → woocommerce.payment_enabled` is `false` — the owner
+> finishes it in wp-admin). Seeding + verifying the catalog over the Store API is the whole job; never call
+> `/checkout` or block on it. See the cookbook §4.
+
 ## Step 6 — Hand off
 
 Update `state.json` (`provision` stays `completed`; advance `stage` toward the frontend **data**
 phase) with a fresh `updated_at`. The backend now holds the content; Step 6's data wiring points the
-frontend at `urls.rest_api`.
+frontend at `urls.rest_api` (and, for a store, `urls.store_api`).