@hostinger/mcp 3.2.2 → 3.3.1

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

@@ -0,0 +1,228 @@
+---
+name: headless-step-content-model
+description: "Step 4 (content model) of the Hostinger Headless flow. Prepare phase: turns brief.md into a content helper (content-model.md) — fixed Title/Description plus a tailored generation prompt per section (Navigation, Pages, Articles) — and generates the drafts/images, no live backend needed. Push phase: routes to the backend subfolder to create it the backend's way once provision is ready."
+---
+
+# headless-step-content-model
+
+Two phases around the **instance barrier** (see the top-level `SKILL.md`):
+
+- **Prepare — no instance.** Build the content helper from `brief.md` and generate the content it
+  calls for. Runs *during* the provision wait; needs only the brief.
+- **Push — needs the instance.** Create that content in the backend. Gated on
+  `provision.status == "completed"`; routes to `wordpress/` or `ecommerce/`.
+
+**In:** `brief.md`. **Out:** `content-model.md` (+ any generated media under
+`~/.hostinger/<domain>/media/`).
+
+> Don't wait for provisioning — the helper comes from the brief alone.
+
+---
+
+## Prepare phase — write the content helper (no instance)
+
+`content-model.md` is a lightweight helper, not a schema. Fill the **fixed values** from the brief and
+write a **generation prompt** for each section — tailored to *this* site, not generic. Then run those
+prompts to produce the drafts (and images), so the push phase is just upload.
+
+Write `content-model.md` from this template, adapting every prompt to the brief's purpose, audience
+and tone:
+
+```markdown
+# Content — <domain>
+
+> Content helper prepared from brief.md on <today>. Fixed values are set; each prompt is run
+> during the provision wait to generate the content and media. Push to the backend happens later.
+
+## Title
+<site name, from the brief>
+
+## Description
+<one–two line site description / default meta, from the brief>
+
+## Navigation
+> Generate the primary menu from the site's pages in reading order (<list the brief's pages>).
+> Short labels; note which items are static pages vs. listing pages. Add a footer menu if the
+> brief implies one (socials, contact).
+
+## Pages
+> Generate each page the brief lists. For every page: title, slug, a short section outline, the
+> copy for static pages (e.g. About, Contact), and SEO title + description.
+> <bullet the brief's pages with their one-line purpose>
+
+## 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 (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 (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:
+
+- **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 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
+  it on the store.
+- **Don't block on design.** The design step (5) owns the look, and it runs in parallel during the
+  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 — 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)
+
+This is still prepare work and needs no live backend: you pick the photos and record their URLs here,
+and the push phase uploads them.
+
+1. **Find candidates.** Use one photo per article, matching its subject and destination.
+   - With an `UNSPLASH_ACCESS_KEY` in the environment, use the official API:
+     `GET https://api.unsplash.com/search/photos?query=<subject>&orientation=landscape` with header
+     `Authorization: Client-ID <key>`.
+   - Without a key, use web search limited to `unsplash.com` (e.g. "unsplash photo Lisbon tram") and
+     take the photo id from the result URL: the last segment of `unsplash.com/photos/<slug>-<id>`, or
+     the whole segment for `unsplash.com/photos/<id>`.
+   - Don't call `unsplash.com/napi/…`. It sits behind a bot challenge and returns 401.
+2. **Resolve a direct file URL.** `GET https://unsplash.com/photos/<id>/download?force=true` (don't
+   follow the redirect) answers `302` with `Location: https://images.unsplash.com/photo-<…>?…`. The
+   `dl=` parameter in it also carries the photographer's name. Drop the query string and request a
+   web size: `https://images.unsplash.com/photo-<…>?w=1600&q=80&fm=jpg&fit=max`. The upload ability
+   needs this direct file URL, which returns 200 with `image/jpeg`. A photo *page* URL won't work.
+3. **Look before you keep it.** Download a small preview (`?w=500`) and view it. Search snippets
+   only show captions, and a photo often isn't quite what its title says. Reject anything off-topic.
+   If nothing fits exactly, take the closest real photo and note the gap rather than mislabel it.
+4. **Write alt text from what the photo shows**, not from the article's image brief. For example,
+   use "Shopfronts and parked scooters on a Hanoi street" even if the article is about rain.
+5. **Record it** under each article in `content-model.md`:
+
+   ```markdown
+   Image: https://images.unsplash.com/photo-<…>?w=1600&q=80&fm=jpg&fit=max
+   Image credit: <Photographer> — https://unsplash.com/photos/<id> (Unsplash License)
+   Image alt: <what the photo shows>
+   Image file: <site>-<subject>.jpg
+   ```
+
+Unsplash photos are free to use under the Unsplash License. Still credit the photographer: the push
+phase stores "Photo by <Photographer> on Unsplash" as the image caption.
+
+Then update `state.json`: set `stage` to the next prepare stage still to do, fresh `updated_at`. Do
+**not** advance past the barrier here.
+
+---
+
+## Push phase — create it the backend's way (needs the instance)
+
+Only once `provision.status == "completed"` (re-verified against `hosting_websites_list-setups`),
+route on the brief's **Suggested backend** and follow that subfolder, which maps the helper onto the
+live backend — for WordPress, through the per-site WP MCP's ability tools (the installation JWT
+authenticates that MCP session; `wp/v2` REST is the public read surface, not a write path for the
+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` (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
+> `content-model.md` unwritten, mark content-model `skipped` in the run log, and go straight to the
+> frontend step.
+
+After the push completes, update `state.json` and continue to the frontend **data** phase.

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

@@ -0,0 +1,75 @@
+---
+name: headless-step-content-model-ecommerce
+description: "Push phase of Step 4 for a Hostinger Ecommerce backend: create the catalog through the hostinger-ecommerce MCP — products (physical/digital) priced in minor units, product images from URLs, optional variants — on the store from site.json. Verified against the public Storefront V2 API. Idempotent, instance-gated."
+---
+
+# headless-step-content-model-ecommerce
+
+**Push phase — needs the store.** Run after provision created the store + custom sales channel (ids in
+`site.json → ecommerce`). All writes go through the **`hostinger-ecommerce`** MCP (`ecommerce_*`,
+OAuth). Prices are **integers in minor units** (cents) and live on **variants**.
+
+**In:** `content-model.md` (prepared catalog), `site.json` (`ecommerce.store_id`). **Out:** products +
+images created in the store; ids recorded back into `content-model.md`.
+
+> If the `hostinger-ecommerce` MCP tools aren't available, don't stop — see the prerequisite in
+> `../../03-provision/ecommerce/SKILL.md` (add the server, and if you can't reconnect your session,
+> drive the stdio server directly rather than blocking).
+
+## Step 1 — Create products (idempotent)
+
+List first so a re-run doesn't duplicate: `ecommerce_products_list { store_id }` — match by title/slug;
+reuse existing ids. For each product in the helper:
+
+```json
+{ "operation": "ecommerce_products_create-physical",
+  "params": { "store_id": "store_…", "name": "…", "price": 3999, "description": "…" } }
+```
+
+- `price` is minor units (3999 = $39.99); currency defaults to the store's. Each create makes one
+  **variant** (its `id` is what checkout needs — read it from the product detail/list).
+- Digital goods: `ecommerce_products_create-digital` (takes a `download_url`).
+- Multiple variants (sizes/flavours): `ecommerce_product-variants_create { store_id, product_id,
+  options:[{name,value}], prices:[{amount}] }`.
+- Batch several creates with `multi-execute` to keep it fast.
+
+## Step 2 — Product images (one call each)
+
+`ecommerce_products_upload-and-attach-image { store_id, product_id, image_url, is_thumbnail: true }` —
+fetches the image from a public URL and attaches it (raster only, no SVG, ≤15MB, HTTPS, ≤1 redirect).
+Unsplash direct URLs (`https://images.unsplash.com/photo-…?w=1200&q=80&fm=jpg&fit=max`) work directly.
+Source images as in the parent `../SKILL.md` (Unsplash). The store stores its own CDN copy
+(`cdn.zyrosite.com`), so the storefront never depends on the source URL.
+
+> Idempotency: check the product's existing `images`/`thumbnail` before attaching so a re-run doesn't pile
+> on duplicates.
+
+## Step 3 — Collections
+
+The API does not expose a collection-create op in this flow, and `product_collections` comes back empty.
+Represent collections (e.g. Proteins / Supplements) as a **frontend mapping** in the storefront
+(`lib/site.ts` → product-slug → collection), and record that mapping in `content-model.md`. If a real
+collection API becomes available, prefer it.
+
+## Step 4 — Verify (public Storefront V2, no auth)
+
+Keyed on the **sales channel** (`site.json → ecommerce.sales_channel.id`):
+
+- `GET https://api-ecommerce.hostinger.com/v2/channels/<scha_*>/products?limit=100` → all products, each
+  with `variants[].prices[]` (amount in minor units + currency `decimal_digits`/`template`), `thumbnail`
+  and `images[]`. Count matches the plan.
+- Detail resolves by **product id** (`…/products/<id>`); a **slug 404s** on detail — map slug→id from the
+  list in the frontend.
+
+## Step 5 — Hand off
+
+Record the id map in `content-model.md` (`## Created in the store`: product → slug → id → variant id →
+price → image). Update `state.json` (advance `stage` toward frontend; leave `provision`). The storefront
+(Step 6) reads the public Storefront V2 API for the channel; checkout is
+`POST /channels/<scha_*>/checkout` (needs a payment method — see the provision payment gate).
+
+> **No payment method = no checkout to seed or verify.** When `site.json → ecommerce.payment_enabled`
+> is `false` (free account / no paid Ecommerce plan — see the provision gate), the catalog push here is
+> **complete on its own**. There is nothing to seed for checkout, and you must **not** test the checkout
+> endpoint or wait on it — seeding products and verifying them over the Storefront V2 API is the whole
+> job. Hand off normally.

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

@@ -0,0 +1,223 @@
+---
+name: headless-step-content-model-wordpress
+description: "Push phase of Step 4 for a headless WordPress backend: open an authenticated session to the per-site WP MCP with the installation JWT, then create the content helper's Title/Description, categories, media, pages, posts and navigation through the MCP ability tools. wp/v2 REST is the public read surface, not a write path for this token. Idempotent, instance-gated."
+---
+
+# headless-step-content-model-wordpress
+
+**Push phase — needs the live instance.** Run only after `provision.status == "completed"` (re-verify
+against `hosting_websites_list-setups`). It maps the backend-agnostic `content-model.md` onto real
+WordPress objects.
+
+**In:** `content-model.md`, `site.json` (both prepared earlier), generated media under
+`~/.hostinger/<domain>/media/`. **Out:** content created in WordPress; created IDs recorded back into
+`content-model.md`.
+
+## What creates what — and what authenticates it
+
+The Hostinger **management** MCP (`wordpress_*`) is infra-only: it installs WordPress, plugins and
+themes but has **no content endpoints**.
+
+Writes go through the **per-site WP MCP** (the Hostinger AI Assistant plugin), authenticated with the
+installation JWT. **The JWT authenticates the MCP endpoint only** — it is wired as the MCP server's
+`authenticate_request`, and the plugin registers no global `determine_current_user` /
+`rest_authentication_errors` filter. So a raw `POST /wp/v2/posts` with this token is **not**
+authenticated; the admin user context (`wp_set_current_user`) exists only *inside* an MCP session.
+
+| Surface | Base (from `site.json`) | Role |
+|---|---|---|
+| **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**, **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
+
+Mint a short-lived token through the Hostinger connector:
+
+```json
+{ "operation": "wordpress_installations_jwt-token",
+  "params": { "username": "<site.json username>", "software": "<site.json wordpress.install_id>" } }
+```
+
+Returns `token` (+ `mcp_url`, already stored as `urls.wp_mcp`). Connect to `urls.wp_mcp` as an MCP
+client (`initialize` → `tools/list` → `tools/call`) and send the token on **every** request as:
+
+- `X-Hostinger-JWT-Token: <token>` — the plugin's preferred header (checked first), **or**
+- `Authorization: Bearer <token>` — accepted as a fallback (case-insensitive `bearer ` prefix).
+
+The token lives ~24 h — mint on demand, **never print, log, or write it to `site.json` /
+`content-model.md`**. If a call returns `401/403` with `token_invalid`/`invalid_api_key`, the token
+expired or was revoked → re-mint and reconnect.
+
+> **Transport gotchas (streamable HTTP MCP).** The endpoint is session-based: `initialize` returns an
+> **`Mcp-Session-Id` response header** — capture it and send it on **every** subsequent request
+> (`tools/list`, `tools/call`), or they fail with `-32600 Missing Mcp-Session-Id header`. Send
+> `Accept: application/json, text/event-stream`. After `initialize`, post the `notifications/initialized`
+> notification, and **tolerate a non-2xx on it** (it can answer 404 with no body — harmless; don't let
+> it abort the session). A raw curl/HTTP client works fine for all this.
+
+## Step 2 — Discover the ability tools
+
+The server advertises either every ability as its own tool, or three **discovery meta-tools**
+(discover → get-info → execute) to keep `tools/list` small. Call `tools/list` first and work with
+what's there; with discovery, list abilities, then execute by ability name. The content tools that
+cover this step (exact names come from discovery — don't hardcode them):
+
+`SettingsTools` · `CategoriesTools` · `TagsTools` · `MediaUploadTools` / `MediaTools` · `PagesTools` ·
+`PostsTools` · `MenusTools` / `NavigationTools` · `SeoTools`. A generic
+`RestEndpointTool` can reach any `wp/v2` route *through the authenticated session* if no dedicated tool
+fits.
+
+Seen on a live install (Hostinger AI Assistant, discovery mode): the meta-tools are
+`hostinger-ai-discover-abilities`, `hostinger-ai-get-ability-info { name }` and
+`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 — 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)
+
+Every create is **list/get-by-slug first, then create only if absent** — a re-run must not duplicate.
+Use the matching read ability (or `RestEndpointTool` → `GET /wp/v2/posts?slug=…&status=any`): a hit →
+reuse its `id`; empty → create. Capture each returned `id` and record the id map back into
+`content-model.md` so later references resolve without re-querying.
+
+## Step 4 — Create in dependency order
+
+0. **Remove WordPress's default content first.** A fresh install ships a **"Hello world!" post**
+   (id 1), a **"Sample Page"**, and a default comment — they will otherwise show up on the live site.
+   Delete the default post (`posts-delete { id: 1, force: true }`) and, if present, the sample page
+   (find it via `pages-search` for slug `sample-page`, then `pages-delete`). This is idempotent: if
+   they're already gone, skip. Leave the default `Uncategorized` category — it's harmless once no post
+   uses it (the frontend only lists categories with posts).
+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 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** — **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 (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",
+  "parameters": {
+    "url": "https://images.unsplash.com/photo-<…>?w=1600&q=80&fm=jpg&fit=max",
+    "filename": "<site>-<subject>.jpg",
+    "title": "<short title>",
+    "alt_text": "<what the photo shows>",
+    "caption": "Photo by <Photographer> on Unsplash",
+    "description": "Source: https://unsplash.com/photos/<id> (Unsplash License)",
+    "post_id": <post id, if the post already exists> } }
+```
+
+- `url` must return 200 with an image content type. A photo *page* URL fails.
+- The result carries the attachment `id` and `source_url`. WordPress also generates the smaller
+  sizes (`300x200`, `768x…`, `1024x…`, …) under `media_details.sizes`, which the frontend can use
+  for `srcset`.
+- Set `filename` yourself, so files in `wp-content/uploads/` have readable names.
+
+**From a local file in `media/`.** Use the Media-upload ability that discovery lists for local
+files.
+
+**Set the featured image.** Pass `featured_media: <id>` when creating the post (Step 4.5). If the
+post already exists (on resume, or when images are added later), use
+`hostinger-ai/posts-update { id, featured_media }`.
+
+**Idempotency trap: don't look up earlier uploads by filename.** `media-search` matches titles and
+content, not filenames or the slug you passed. A search for `<site>-lisbon-tram` finds nothing even
+though the file exists, so a re-run would upload the image again. WordPress then stores the duplicate
+as `…-1.jpg` and silently repoints the post at it. Check this way instead:
+
+1. `posts-get { id }`. If `featured_media` is already set, skip that post. Its image exists.
+2. Otherwise, search by the **title** you set on upload (`media-search { search: "<title>" }`),
+   and reuse a hit.
+3. Only upload when both checks come up empty.
+
+If duplicates do slip in, point each post back at the original with `posts-update`, then delete the
+duplicates with `media-delete { id, force: true }`.
+
+## Step 5 — Verify and record
+
+- Read a couple of created objects back through `wp/v2` (public GET, no auth): e.g.
+  `GET {urls.rest_api}/posts?per_page=1` and check the `X-WP-Total` header against the planned article
+  count; fetch one post with `_embed` to confirm `featured_media` and `categories` resolved.
+- Media: `GET {urls.rest_api}/media?per_page=1` → `X-WP-Total` equals the number of images planned
+  (more means duplicates). `GET {urls.rest_api}/media?include=<ids>` confirms `alt_text` and
+  `caption` on each image. Each `source_url` must return 200 with an image type. Each post's
+  `featured_media` must point at its image.
+- Write the created-id map into `content-model.md` (a `## Created in WordPress` section: object → slug
+  → 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` (and, for a store, `urls.store_api`).