@hostinger/mcp 3.2.2 → 3.3.1

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

@@ -0,0 +1,142 @@
+---
+name: headless-step-provision-ecommerce
+description: "Provision a Hostinger Ecommerce backend for the Hostinger Headless flow: ensure the hostinger-ecommerce MCP is connected, create the headless website (frontend host) and a Hostinger Ecommerce STORE with a custom (headless) sales channel, set shipping + payment, and record it all in site.json."
+---
+
+# headless-step-provision-ecommerce
+
+Provision a **Hostinger Ecommerce** backend for `<domain>` and prove it is ready. Two distinct things:
+
+1. A **headless website** (`type: "headless_ecommerce"`) — this is only the **hosting slot for the
+   storefront you'll build**. It installs **no store engine** (no `/cms`, no API on the domain).
+2. A **Hostinger Ecommerce store** — a separate object created through the **Ecommerce API**, with a
+   **custom (headless) sales channel**. The storefront reads this store's **public Storefront Core V2
+   API**, keyed on the sales channel. This is the real backend.
+
+**Out:** `site.json` (store id, custom sales channel id, URLs).
+
+> ## ⚠️ Prerequisite: the `hostinger-ecommerce` MCP server must be connected
+> Store management is **not** in the `hosting`/`wordpress` MCP groups — it's the separate
+> **`hostinger-ecommerce`** group (`ecommerce_*` ops, OAuth-backed, no API token needed). If those
+> tools aren't available, add the server and **reconnect the session** before continuing:
+> ```bash
+> claude mcp add-json hostinger-ecommerce '{"command":"npx","args":["--package=@hostinger/mcp@latest","hostinger-ecommerce-mcp"],"env":{"USER_AGENT":"extension;claude-code;via-cursor;1.4.2"}}' --scope user
+> ```
+> (For other tools, enable the **Ecommerce** MCP in the Hostinger Connector.) A newly added MCP server
+> only loads on a session restart/reconnect.
+>
+> **Can't restart your own session? Don't block — drive the server directly.** A coding agent usually
+> can't reconnect itself, so instead of stopping, run the stdio server yourself and speak MCP to it:
+> spawn `npx --package=@hostinger/mcp@latest hostinger-ecommerce-mcp` (same `USER_AGENT` as above) and
+> send newline-delimited JSON-RPC over its stdin/stdout — `initialize` → the `notifications/initialized`
+> notification → `tools/list` → `tools/call`, where the tools are `search` / `execute` / `multi-execute`
+> (call ops exactly as in-session: `{ "name": "execute", "arguments": { "operation": "…", "params": {…} } }`).
+> It self-authenticates with the same stored Hostinger OAuth creds as the other connected servers, so
+> there is **no token to handle** (keep any secret off the command line). Your sandbox may ask the user
+> to approve spawning it — ask once, then proceed. Only fall back to asking the user to restart if
+> driving the server directly isn't permitted.
+>
+> Verify the tools work (in-session or via the direct drive) with a search — e.g. "list stores" →
+> `ecommerce_stores_list` — before proceeding.
+> The authoritative, always-current build guide is `ecommerce_miscellaneous_custom-storefront-setup-instructions` — read it once per build.
+
+All website-lifecycle calls go through the `hosting` connector (`execute`); all store calls through the
+`hostinger-ecommerce` MCP.
+
+## Step 1 — The headless website (frontend host)
+
+Same lifecycle as `../wordpress/SKILL.md` Steps 1–2, but `type: "headless_ecommerce"`:
+
+1. Detect: `hosting_websites_list` / `hosting_websites_list-setups` (exact-match the domain). `completed`
+   → adopt. `running` → poll. `failed` → stop, point at hPanel. If `website_type` is not `headless`
+   (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).
+
+## Step 2 — Resolve or create the store + custom sales channel
+
+`ecommerce_stores_list` → reuse an existing store if this build already made one; otherwise create:
+
+```json
+{ "operation": "ecommerce_stores_create",
+  "params": { "name": "<store name>", "country_code": "US", "company_email": "<email>",
+    "company_name": "<store name>", "language": "en",
+    "sales_channel": { "type": "custom", "external_id": "<slug>-headless" } } }
+```
+
+This returns `store.id` (`store_*`) **and** a custom `sales_channel.id` (`scha_*`) in one call — the
+custom channel is what the headless storefront is keyed on. (You can also add one later with
+`ecommerce_sales-channels_create { store_id, type:"custom", name }`.) Currency comes from
+`country_code` (`default_currency_code`); all prices are **minor units** (cents).
+
+## Step 3 — Store readiness: shipping + payment
+
+A store needs ≥1 shipping zone and ≥1 payment method to check out.
+
+- **Shipping:** `ecommerce_shipping_set-store { store_id, price }` (minor units; 0 = free).
+- **Payment:** `ecommerce_payments_enable-manual-method { store_id, title }`.
+
+> **Known gate — free accounts have no payment method, and therefore no checkout.** On a **free
+> account** (and any account/store without a paid Hostinger Ecommerce plan), `enable-manual-method`
+> returns **HTTP 402**, and checkout later fails with `400 payment_provider_not_configured`. This is
+> **expected, not an error** — payment, and therefore checkout, is simply unavailable on the plan. The
+> catalog and the storefront still work fully. **Never block, stop, loop or retry the build on this:**
+> - Record `payment_enabled: false` in `site.json` (set `shipping_enabled` as usual).
+> - Tell the user in one line that checkout needs a paid Ecommerce plan, and carry straight on.
+> - Treat the 402 as a normal outcome — don't surface it as a failure or re-attempt the call.
+> - Never ask the user for payment credentials.
+>
+> Every downstream stage reads `site.json → ecommerce.payment_enabled` and, when it is `false`, skips
+> all checkout wiring and verification (see content-model Step 5, frontend, deploy). A store with
+> `payment_enabled: false` is a **complete, valid build** — a browsable catalog without checkout.
+
+## Step 4 — Verify
+
+- `ecommerce_stores_metadata { store_id }` → `has_shipping` true; `has_payment_methods` (may be false,
+  see the gate); read `default_currency` (`decimal_digits`, `template`) here, don't guess.
+- Public Storefront V2 answers for the channel (no auth):
+  `GET https://api-ecommerce.hostinger.com/v2/channels/<scha_*>/products?limit=100` → 200 (empty until
+  content-model seeds products — fine here).
+- `GET https://<domain>/` returns the Hostinger default page until the storefront is deployed — expected.
+
+## Step 5 — Record `site.json`
+
+```json
+{
+  "backend": "ecommerce",
+  "website_type": "headless",
+  "order_id": 1007223428,
+  "username": "u…",
+  "ecommerce": {
+    "store_id": "store_…",
+    "sales_channel": { "id": "scha_…", "type": "custom", "external_id": "…-headless" },
+    "currency": "usd",
+    "payment_enabled": false,
+    "shipping_enabled": true
+  },
+  "urls": {
+    "site": "https://<domain>",
+    "storefront_api": "https://api-ecommerce.hostinger.com/v2/channels/<scha_*>",
+    "store_admin": "https://ecommerce.hostinger.com/store/<store_*>"
+  },
+  "provisioned_at": "…",
+  "verified_at": "…"
+}
+```
+
+No secrets in `site.json`. After deploy, link the channel to the live domain with
+`ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (done in the deploy stage).

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

@@ -0,0 +1,154 @@
+---
+name: headless-step-provision-webapp
+description: "Provision a plain Node.js app host for the Hostinger Headless flow: create an empty website (no WordPress, no store engine, no /cms), optionally a MySQL database, then record it in site.json. For any webapp / SPA / app that brings its own code and data."
+---
+
+# headless-step-provision-webapp
+
+Provision a bare **Node.js app host** for `<domain>` and prove it is ready. This is the backend for
+**any webapp, SPA or app** that brings its own code (and, if it needs one, its own database) — there is
+no CMS and no store engine here. The site is an **empty website**: just the hosting slot that the
+frontend step builds into and the deploy step ships to as a Node.js application. **Out:** `site.json`.
+
+> **Not WordPress, not Ecommerce.** Never provision `headless_wordpress` / `headless_ecommerce` for a
+> webapp, and never install WordPress at `/cms`. A webapp owns its own routes, data and rendering.
+
+All website/database 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: once 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–5, 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 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 is a different kind (`website_type` is `headless`, or a WordPress/store site),
+   stop and tell the user — this domain already hosts something else.
+
+## Step 2 — Create (only when nothing exists)
+
+1. Pick the plan: `hosting_orders_list { "statuses": ["active"] }`. One active order → use it; several
+   → ask the user which.
+2. Start the setup as an **empty website** — **omit `type`** (no WordPress, no store):
+
+   ```json
+   { "operation": "hosting_websites_start-setup",
+     "params": { "order_id": <order_id>, "domain": "<domain>" } }
+   ```
+
+   `domain` must be a **customer-owned** domain. For a temporary `*.hostingersite.com` subdomain,
+   **omit `domain`** — the setup generates one itself. Don't call a separate subdomain op to make one
+   first: there's no need, and passing a generated free subdomain back as `domain` fails with
+   `422 … Free subdomains cannot be provided`. The response then carries the generated domain: if it
+   differs from the workspace directory name, move `~/.hostinger/<old>/` to `~/.hostinger/<new>/`,
+   update the domain in `brief.md`, and tell the user the new domain.
+3. Poll `hosting_websites_list-setups { "domain": "<domain>" }` every ~15 s until `completed`
+   (typically under a minute; allow a few minutes). `failed` → stop, point at hPanel.
+
+## Step 3 — Database (only if the app needs one)
+
+Skip this step entirely for an app with no database (static SPA, an app that talks to an external API).
+This is **join-half** work — it needs the live website, so run it once `provision.status == "completed"`.
+
+**Preferred — let the platform create the database and inject the credentials:**
+`hosting_databases_setup-website { username, domain }` creates a MySQL database, **generates the
+password, writes `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD` / `DATABASE_URL` into the
+website's environment variables, and restarts the app — in one call.** The password is never returned,
+so there is **nothing to persist and nothing to lose across sessions** — the app reads it from the
+environment. (It 422s if any of those env vars already exist; clear them first with
+`hosting_nodejs_replace-environment-variables`. Frameworks that bake vars into the build — Next.js,
+`NEXT_PUBLIC_*` — only pick up the values on the deploy build.)
+
+> **⚠️ A later `hosting_nodejs_replace-environment-variables` wipes these credentials.** That call is a
+> **full replace**, and when you list the current vars first the `DB_PASSWORD` (and `DATABASE_URL`) read
+> back **masked** (`********`) — the generated password is unknown, so you cannot resend it and the DB
+> env is lost. One rule, pick one:
+> - **(a) Set every other app env var first, and call `setup-website` last** — then nothing has to
+>   replace the env again.
+> - **(b) If a later replace is unavoidable**, reset the password with
+>   `hosting_databases_change-password { username, name, password }` and resend **all** of `DB_HOST`,
+>   `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` and `DATABASE_URL` with the new password in that same
+>   full replace.
+
+**Manual alternative** — only when you need a specific name/user or finer control:
+
+1. `hosting_databases_create` with a name, a user, and a password you generate — name and user are
+   prefixed with the account username automatically. Read the full, prefixed `name`/`user` back from
+   `hosting_databases_list`.
+2. **Which host the app connects to:** the app runs **on the website**, so Node.js connects to
+   **`127.0.0.1:3306`** — never `localhost` (it can resolve to IPv6 `::1`, and not every database user
+   has that grant), and never the external `host` from `hosting_databases_list` (`srvNNNN.hstgr.io`,
+   which has no grant for connections from the server itself).
+3. **Set the env vars now, while you still hold the generated password.** The password is **not persisted
+   anywhere** (never in `site.json`), so set `DB_HOST=127.0.0.1`, `DB_PORT=3306`, `DB_NAME`, `DB_USER`,
+   `DB_PASSWORD`, plus `DATABASE_URL=mysql://USER:PASSWORD@127.0.0.1:3306/NAME` (URL-encode USER/PASSWORD)
+   right here with `hosting_nodejs_replace-environment-variables` (a **full replace** — list current keys
+   first; values come back masked; send the complete set with real values). Saving restarts the process;
+   build-time vars need a fresh deploy (`hosting_deploy`) afterwards. **Don't defer this to deploy:** on
+   a **cross-session resume** the generated password is gone, so you must **reset it** with
+   `hosting_databases_change-password { username, name, password }` and set the env vars from the new one.
+4. **Never** put the password in source, a committed `.env`, client-side JavaScript, or a chat reply;
+   never print it once stored.
+
+## Step 4 — Verify
+
+| Check | How | Expect |
+|---|---|---|
+| Website exists | `hosting_websites_list` exact row | the row is present, `username` known |
+| Setup finished | `hosting_websites_list-setups` exact row | `status: completed` |
+| Database reachable *(only if created)* | `hosting_databases_list { username }` | the prefixed db + user are listed |
+
+`GET https://<domain>/` returns the Hostinger default page (or 403) until the frontend is deployed —
+expected, not a failure. There is **no `/cms` and no API** on this domain; the app itself serves every
+route once it is deployed (Step 8).
+
+If a check fails: retry once after ~30 s; if it still fails, stop and point the user at hPanel.
+
+## Step 5 — Record `site.json`
+
+```json
+{
+  "backend": "webapp",
+  "website_type": "empty",
+  "order_id": 1007223428,
+  "username": "u…",
+  "runtime": "nodejs",
+  "database": {
+    "enabled": false,
+    "engine": "mysql",
+    "name": "u…_appdb",
+    "user": "u…_app",
+    "host": "127.0.0.1",
+    "port": 3306
+  },
+  "urls": {
+    "site": "https://<domain>"
+  },
+  "provisioned_at": "…",
+  "verified_at": "…"
+}
+```
+
+No passwords or tokens in `site.json` — only the non-secret connection shape (host/port/name/user). Set
+`"database": { "enabled": false }` (and drop the rest) when the app needs no database.
+
+## Deploy & content model (what happens next)
+
+- **Content model is skipped for a webapp** — there is no CMS or store to seed; the app owns its own
+  data. The content-model router (`../../04-content-model/SKILL.md`) passes straight through to the
+  frontend step for this backend.
+- **Deploy** is a standard Node.js application deploy, handled by `../../08-deploy/SKILL.md`: it archives
+  the **source** (not the build output; exclude `node_modules/`, `.next/`, `dist/`, build output and
+  `.git/`), then deploys with `hosting_deploy` (`type: "nodejs"`, upload + server-side `npm install` +
+  build, one shot) passing the framework's `appType` + `outputDirectory` inline, and polls
+  `hosting_get-deployment` until the build completes. Any supported `appType` works (Next.js, Nuxt,
+  Express, NestJS, Fastify, Vite/React/Vue SPA, …). There is no `/cms` to preserve here, so the whole
+  root is the app.

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

@@ -0,0 +1,249 @@
+---
+name: headless-step-provision-wordpress
+description: "Provision a headless WordPress backend for the Hostinger Headless flow: create the headless website with WordPress at /cms, verify and self-heal, then record it in site.json."
+---
+
+# headless-step-provision-wordpress
+
+Create the headless WordPress backend for `<domain>` and prove it is ready. One platform call lays
+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).** 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. **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.
+2. Start the setup:
+
+   ```json
+   { "operation": "hosting_websites_start-setup",
+     "params": { "order_id": <order_id>, "type": "headless_wordpress", "domain": "<domain>" } }
+   ```
+
+   `domain` must be a **customer-owned** domain. For a temporary `*.hostingersite.com` subdomain,
+   **omit `domain`** — the setup generates one itself. Don't call a separate subdomain op to make one
+   first: there's no need, and passing a generated free subdomain back as `domain` fails with
+   `422 … Free subdomains cannot be provided`. The response then carries the generated domain:
+   if it differs from the workspace directory name, move `~/.hostinger/<old>/` to `~/.hostinger/<new>/`,
+   update the domain in `brief.md`, and tell the user the new domain.
+   Admin credentials are generated by the platform; never ask the user for a password.
+3. Poll `hosting_websites_list-setups { "domain": "<domain>" }` every ~15 s until `completed`
+   (typically under a minute; allow a few minutes). `failed` → stop, point at hPanel.
+
+## 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 |
+|---|---|---|
+| Site is headless | `hosting_websites_list` exact row | `website_type: "headless"` |
+| WordPress at `/cms` | `wordpress_installations_list { "username": "<username>", "ownership": "all" }`, exact-match `domain` | row with `directory: "cms"`, `is_valid: true`; note its `id` |
+| REST API answers | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200, JSON array |
+| AI Assistant + MCP loaded | `GET https://<domain>/cms/wp-json/` → `namespaces` | contains `hostinger-ai-assistant/v1` and `mcp` |
+| JWT mintable | `wordpress_installations_jwt-token { username, software: <id> }` | returns `token`, `mcp_url` |
+
+Notes:
+
+- `wordpress_installations_list` can lag a few seconds behind `completed` and return `[]` — retry
+  briefly before failing. Its `domain` filter is a substring match, so exact-match the row.
+- The install record's `url` may say `http://`; always use `https://` URLs.
+- `GET https://<domain>/` returns 403 until the frontend is deployed — expected, not a failure.
+- **Never print, log or store the JWT.** It is minted on demand (24 h lifetime) by whichever stage
+  needs the per-site WP MCP; only `mcp_url` is recorded.
+
+If a check fails: retry once after ~30 s; if it still fails, stop and point the user at hPanel.
+
+## 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
+{
+  "backend": "wordpress",
+  "website_type": "headless",
+  "order_id": 1007223428,
+  "username": "u…",
+  "wordpress": {
+    "install_id": "30…",
+    "directory": "cms",
+    "admin_login": "…"
+  },
+  "seo": {
+    "plugin": "wordpress-seo",
+    "enabled": true
+  },
+  "urls": {
+    "site": "https://<domain>",
+    "cms": "https://<domain>/cms",
+    "wp_admin": "https://<domain>/cms/wp-admin",
+    "rest_api": "https://<domain>/cms/wp-json/wp/v2",
+    "wp_mcp": "<mcp_url from the JWT call>"
+  },
+  "provisioned_at": "…",
+  "verified_at": "…"
+}
+```
+
+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`.