hostinger-api-mcp 3.28.6 → 3.29.0

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

@@ -1,275 +1,106 @@
 ---
 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."
+description: "Push phase of Step 4 for a headless WordPress backend: write the drafted content into one content.json and run push-content.mjs, which creates the site title, categories, tags, images, pages, posts, menu, Yoast fields and the WooCommerce catalog through the per-site WP MCP and records the created ids. By-hand recipe only when the script can't run. Idempotent, instance-gated."
 ---
 
 # headless-step-content-model-wordpress
 
-**Push phase — needs the live instance.** Run only after `provision.status == "completed"`. It maps the backend-agnostic `content-model.md` onto real
-WordPress objects.
+**Push phase — needs the live instance.** Run only after `provision.status == "completed"`.
 
-**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**.
+**In:** `content-model.md`, `site.json`, the drafts from the prepare phase. **Out:** the content in
+WordPress, and the created-id map in `content-model.md`.
 
 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 |
+installation JWT. The management MCP (`wordpress_*`) has no content endpoints, and `wp/v2` REST is the
+public read surface the frontend uses, not a write path for that token. `push-content.mjs` handles all
+of this: you write one file and run one command.
 
-> **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).
+Also on this step, when the brief calls for them:
 
-> **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.
+- **A store** (`site.json → woocommerce.enabled: true`): the catalog goes in the same content file
+  (`store` below). Checkout stays owner-completed; see [`woocommerce.md`](woocommerce.md) §4.
+- **A contact form** (`site.json → contact_form.enabled: true`): after the push, follow
+  [`contact-form.md`](contact-form.md) to find the form id and deploy the spam guard.
+- **Custom post types, taxonomies or a settings page:** deploy the plugin from
+  [`custom-plugins.md`](custom-plugins.md) before the push, and create its entries with `cpt-create` after.
 
-> **Needs more than posts and pages? See [`custom-plugins.md`](custom-plugins.md).** The per-site MCP can
-> create content *data* but can't register a **custom post type**, a **custom taxonomy**, or a **global
-> settings page** (footer text, phone, social links the frontend reads). When the content model calls for
-> those, author a small custom plugin and deploy it into the headless `/cms` with
-> `hosting_deploy { type: "wordpress-plugin", headless: true }`, exposing everything over REST for the
-> frontend. **Deploy the plugin first** (the schema — the deploy activates it), then the steps below populate
-> its entries through the MCP's native `cpt-create` ability (custom-taxonomy terms are seeded in the plugin — see the cookbook).
+## Step 1 — Write `content.json`
 
-> **A contact form on this site? See [`contact-form.md`](contact-form.md).** When the brief's
-> **Must-haves** include a contact form (`site.json → contact_form.enabled: true`), provision installed
-> **Contact Form 7**; this push resolves the form's numeric id + field names (in the **same session**)
-> and records them into `site.json` so the Step 6 frontend can submit to CF7's public feedback endpoint.
-> Run the **Contact form** section after the WordPress content below.
-
-## Step 1 — Open the authenticated MCP session
-
-Mint a short-lived token through the Hostinger connector:
+Write `~/.hostinger/<domain>/content.json` in one go, from the drafts you generated in the prepare phase.
+Leave out any section the site doesn't have. Every field below is what the script accepts; anything
+else is refused, with the field named.
 
 ```json
-{ "operation": "wordpress_installations_jwt-token",
-  "params": { "username": "<site.json username>", "software": "<site.json wordpress.install_id>" } }
+{
+  "site": { "title": "Crumb & Co", "description": "Sourdough baked daily in Lisbon" },
+  "categories": [ { "name": "Bread", "slug": "bread" } ],
+  "tags": [ { "name": "Sourdough", "slug": "sourdough" } ],
+  "pages": [
+    { "slug": "about", "title": "About us", "content": "<p>…</p>", "excerpt": "…",
+      "image": { "url": "https://…", "alt": "…" },
+      "seo": { "title": "…", "description": "…" } }
+  ],
+  "posts": [
+    { "slug": "why-sourdough", "title": "Why sourdough", "content": "<h2>…</h2><p>…</p>", "excerpt": "…",
+      "categories": ["bread"], "tags": ["sourdough"],
+      "image": { "url": "https://images.unsplash.com/photo-…?w=1600&q=80&fm=jpg&fit=max",
+                 "alt": "Loaves on a wooden shelf", "title": "Loaves on a shelf",
+                 "filename": "crumb-loaves.jpg", "caption": "Photo by <Photographer> on Unsplash" },
+      "seo": { "title": "…", "description": "…", "focus_keyword": "…" } }
+  ],
+  "menu": { "name": "Primary", "items": [ { "title": "About", "page": "about" }, { "title": "Journal", "url": "/journal" } ] },
+  "store": {
+    "categories": [ { "name": "Breads", "slug": "breads" } ],
+    "products": [ { "sku": "CR-LOAF", "name": "Country loaf", "price": "6.50", "description": "<p>…</p>",
+                    "short_description": "…", "categories": ["breads"], "image": { "url": "https://…", "alt": "…" } } ],
+    "coupons": [ { "code": "WELCOME10", "discount_type": "percent", "amount": "10" } ]
+  }
+}
 ```
 
-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`, plus **`cpt-*`** for custom post types. There
-is **no** generic `wp/v2` passthrough tool — every write goes through a dedicated ability, so a `wp/v2`
-route with no matching ability (e.g. the terms of a *custom* taxonomy) isn't reachable from the MCP;
-register and seed those in a custom plugin instead (see the backend's custom-plugins cookbook).
-
-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 (`posts-search`, `pages-search`, `categories-list`, `tags-list`,
-`cpt-search`, `media-search`, …): 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
-
-> **Custom types/settings? Deploy the plugin before this list.** If the content model needs a custom post
-> type, taxonomy or global settings page, deploy that plugin **first** (the deploy activates it — see
-> [`custom-plugins.md`](custom-plugins.md)) so its REST routes exist — then the steps below populate its
-> entries through the MCP's native `cpt-create` ability, as they do core posts and pages (custom-taxonomy
-> terms are seeded in the plugin — the MCP has no taxonomy-term path; see the cookbook).
-
-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> } }
+- **Slugs** are lower-case ASCII with dashes (`about-us`). References are slugs defined in the same
+  file: a post's `categories` and `tags`, a menu item's `page`, a product's `categories`, and a page's
+  or term's `parent`, which must be listed before its child.
+- `content` and `excerpt` are HTML strings. A page can also take `parent` and `menu_order`; a term can take
+  `description` and `parent`.
+- **Images:** `url` must be a direct `https` file URL that answers 200 with an image type: an Unsplash
+  web-size URL, or a Hostinger-AI image `url` (it expires, so generate right before the push; see the
+  content-model `SKILL.md`, *Images* Option A, and leave `caption` empty). `alt` is required. `title` (it
+  defaults to `alt`) is how a re-run finds the upload, so keep it unique per image. The same `url` used
+  twice uploads once.
+- **`seo`** sets the Yoast title, description and focus keyword. It's skipped when `site.json →
+  seo.enabled` is `false`.
+- **`store`** is only for a WooCommerce brief. `price` is a decimal string in major units (`"6.50"`). A
+  product passes any other WooCommerce product field as given (`sale_price`, `stock_quantity`,
+  `attributes`, …). Variations of a variable product are by hand. `discount_type` is `percent`,
+  `fixed_cart` or `fixed_product`.
+
+## Step 2 — Run the push
+
+```bash
+node <skill>/push-content.mjs <domain>
 ```
 
-- `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
+It mints the token itself (never printed), removes WordPress's "Hello world!" post and "Sample Page",
+then creates the site title, terms, images, pages, posts with their featured images, the menu, the
+Yoast fields and the store, each looked up first, so a re-run reuses what exists and updates pages,
+posts and products to match the file. Then it checks the result over public `wp/v2` and the Store API
+(every slug and SKU there once, featured images set, no duplicate uploads), and writes the id map into
+`content-model.md` under `## Created in WordPress` and `## Created in WooCommerce`. Progress goes to
+stderr; stdout is one JSON line with `counts`, `verify` and `ids`.
 
-- 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.
-
-## Contact form (Contact Form 7) *(only when `site.json → contact_form.enabled` is true — skip otherwise)*
-
-Provision installed Contact Form 7. Here, resolve the form the frontend submits to, deploy a tiny
-spam-guard plugin (a headless honeypot), and record both into `site.json`. Full recipe:
-[`contact-form.md`](contact-form.md). In short:
-
-1. **Find the form id (idempotent).** The per-site MCP has **no generic REST ability** and
-   `wpcf7_contact_form` is not a public CPT, so read the id by **probing the public feedback endpoint**:
-   a **`multipart/form-data`** `POST {urls.cms}/wp-json/contact-form-7/v1/contact-forms/<id>/feedback` with
-   `_wpcf7_unit_tag=wpcf7-f<id>-o1`, for `id` in `1`‒`30`. The hit is the id whose `200` JSON reply carries
-   `"contact_form_id": <id>` (plus a CF7 `"status"`) — the default **"Contact form 1"** (fields `your-name`,
-   `your-email`, `your-subject`, `your-message`); `404`/`wpcf7_not_found` is a miss, and anything else
-   (`415`, `403`, `429`, `5xx`) is inconclusive, never a hit. **The content type matters:** CF7 answers
-   `415` to a non-multipart body *before* it looks up the id, so a bare POST would wrongly pick id 1. Reuse
-   it on re-run. CF7's default mail already sends to `[_site_admin_email]`, so no recipient change is needed.
-   *(Fallback if nothing answers: hand the owner the one-click wp-admin login — `wordpress_login_create-links`
-   — to read the id from Contact → Contact Forms, the WooCommerce-checkout-gate owner-handoff pattern.)* See
-   the cookbook for the full method.
-2. **Deploy the spam guard (honeypot).** The `contact-form-7-honeypot` add-on can't work headlessly (it
-   needs a `[honeypot]` form-tag only an owner can add), so deploy a ~15-line `wpcf7_spam` plugin to `/cms`
-   with `hosting_deploy { type: "wordpress-plugin", slug: "cf7-headless-spamguard", headless: true }` — it
-   flags a submission as `spam` (no mail) when a fixed decoy field (`your_website`) is filled. Cookbook §2b.
-3. **Record into `site.json`** — fill the `contact_form` block provision started: `form_id`,
-   `feedback_url` (`{urls.cms}/wp-json/contact-form-7/v1/contact-forms/<form_id>/feedback`), `fields`
-   (the form's input names, e.g. `["your-name","your-email","your-subject","your-message"]`) and
-   `honeypot_field` (`"your_website"`, the decoy the frontend renders empty). Note the form id in
-   `content-model.md` under `## Created in WordPress`.
+| Exit | Meaning | Do |
+|---|---|---|
+| `0` | Everything pushed and verified | Go on to Step 3 |
+| `1` with `invalid` or `error` | The call or a file is wrong; nothing was pushed | Fix what it names and re-run |
+| `1` with `failed` | Those items failed; the rest is in | Fix the cause the `error` names and re-run. If the same item fails twice, create just that item with [`by-hand.md`](by-hand.md) |
+| `2` | It couldn't reach the site (sign-in, the site's MCP, a missing ability); `error` says why | Push with [`by-hand.md`](by-hand.md) |
 
-> **Don't send a real test here.** Resolving the form id + fields is the whole job for this stage; the
-> throwaway `mail_sent` test belongs to **validate** (Step 7), so one dummy email reaches the owner, not
-> several. See the cookbook for the feedback contract and the hidden `_wpcf7*` fields the frontend needs.
+A run cut short (a tool timeout, a kill) is safe to repeat: just run it again.
 
-## Step 6 — Hand off
+## Step 3 — 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`).
+Run the contact-form and custom-type work above if the brief has them. Then update `state.json`
+(`provision` stays `completed`; advance `stage` toward the frontend **data** phase) with a fresh
+`updated_at`. The frontend reads `urls.rest_api` (and, for a store, `urls.store_api`), and nav from
+`content-model.md`.

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

@@ -0,0 +1,31 @@
+# headless — WordPress content push by hand
+
+The recipe `push-content.mjs` runs, for when it exits 2, or for one item that failed twice (create only
+that item). The content is the same as in `content.json` (`SKILL.md` Step 1).
+
+1. **Session.** Mint the token with `wordpress_installations_jwt-token { username, software: <site.json
+   wordpress.install_id> }`; never print, log or store it. POST JSON-RPC to `urls.wp_mcp` with the header
+   `X-Hostinger-JWT-Token: <token>` and `Accept: application/json, text/event-stream`. `initialize`
+   answers an `Mcp-Session-Id` header: send it on every later request. Then post
+   `notifications/initialized`; a 404 on it is harmless. A 401/403 means the token expired: re-mint.
+2. **Abilities.** `tools/list` shows either one tool per ability or the meta-tools
+   `hostinger-ai-discover-abilities`, `hostinger-ai-get-ability-info { name }` and
+   `hostinger-ai-execute-ability { name, parameters }`. Abilities are named `hostinger-ai/<thing>-<action>`;
+   read each schema before use. A result is `{ ability, result }`: the new `id` is `result.id`, a list is
+   `result.data`, and an error is a normal result holding `{ code, message, data: { status } }`.
+3. **Look up, then create.** Search first by slug (`posts-search`, `pages-search`, `categories-list`,
+   `tags-list`, `menus-search` take `slug: [<slug>]`), products by `sku`, coupons by `code`, and reuse a hit.
+4. **In this order:** delete `hello-world` (`posts-search`, `posts-delete`) and `sample-page`; then
+   `wp-settings-update { title, description }`; categories and tags; images with
+   `media-upload-from-url { url, filename, title, alt_text, caption }`; `pages-create` and
+   `posts-create` with `slug`, `status: "publish"`, `categories`, `tags`, `featured_media`; `menus-create`,
+   then `menu-items-create { title: { raw }, type: "post_type", object: "page", object_id, menus }` (or
+   `type: "custom", url`); `seo-bulk-update { posts: [ { id, seo_title, meta_description } ] }`; then
+   `wc-product-categories-create`, `wc-products-create { sku, name, type: "simple", regular_price,
+   categories: [ { id } ], images: [ { id } ] }` and `wc-coupons-create`.
+5. **Two traps.** Pass `title`, `content` and `excerpt` as `{ "raw": "…" }` objects: a bare string is
+   dropped while the create still succeeds. And `media-search` matches titles, not filenames, so before
+   uploading again, check the post's `featured_media` (`posts-get`), then search by the title you set.
+6. **Verify and record.** `GET {urls.rest_api}/posts?per_page=100` (and `/pages`, `/media`) and
+   `GET {urls.store_api}/products?per_page=100` show each item once with its image. Write the id map into
+   `content-model.md` under `## Created in WordPress` (and `## Created in WooCommerce`).

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

@@ -13,7 +13,7 @@ custom post types — but there is **no generic `wp/v2` passthrough** (no `RestE
 
 | Need | Plugin? | Do it with |
 |---|---|---|
-| Blog posts, static pages, categories, media, nav | **no** | per-site WP MCP (`SKILL.md` Step 4) |
+| Blog posts, static pages, categories, media, nav | **no** | per-site WP MCP (`push-content.mjs`, `SKILL.md`) |
 | A **custom post type** — Team, Services, Properties, Testimonials, a restaurant's dishes | **yes** | *Custom post type* below |
 | A **custom taxonomy** — Property Type, Cuisine, Service Area | **yes** | *Custom taxonomy* below |
 | **Global site content** the frontend needs — footer text, phone, address, opening hours, social links, a CTA line | **yes** | *Settings page + public settings route* below |
@@ -25,7 +25,7 @@ custom post types — but there is **no generic `wp/v2` passthrough** (no `RestE
 > headless `/cms` with `hosting_deploy { type: "wordpress-plugin", headless: true }` (see *Deploy* below).
 > Author one only for the *structure and behaviour* the per-site MCP can't express — types, taxonomies,
 > settings, helpers. Don't write a **seed/config plugin** to load WooCommerce catalog data or page content;
-> that goes through the per-site MCP's native abilities (`woocommerce.md`, `SKILL.md` Step 4), never a plugin.
+> that goes through the per-site MCP's native abilities (`woocommerce.md`, `push-content.mjs`), never a plugin.
 
 ---
 

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

@@ -13,11 +13,10 @@ the cart, coupons and checkout.
 
 ## 1 — The one rule: drive the store through the per-site WP MCP
 
-A **custom plugin cannot be installed into a headless `/cms`** from a coding agent (same limit that
-removed `wp-development.md`). So there is **no seed plugin, no WP-CLI, and no REST consumer key in this
-flow.** Instead, the **per-site WP MCP** (the Hostinger AI Assistant — the same JWT session the WordPress
-content push uses, see `SKILL.md` Step 1) exposes **native WooCommerce abilities**. Seed and manage the
-catalog through them, exactly as posts/pages are created.
+There is **no seed plugin, no WP-CLI, and no REST consumer key in this flow**: catalog data goes through
+the WP MCP. Instead, the **per-site WP MCP** (the Hostinger AI Assistant — the same JWT session the WordPress
+content push uses, see `SKILL.md`) exposes **native WooCommerce abilities**. The push seeds the
+catalog through them (§3); call them yourself only by hand or for work after the push.
 
 Relevant abilities (names from `hostinger-ai-discover-abilities`; call `get-ability-info` for each schema
 before use — they mirror the WooCommerce REST v3 shapes):
@@ -65,42 +64,18 @@ divisor: `prices.price` (e.g. `"1999"`) with `prices.currency_minor_unit` (e.g.
 
 ## 3 — Seeding the catalog (content-model push)
 
-Run after provision installed + activated WooCommerce (`site.json → woocommerce.enabled: true`), inside
-the authenticated per-site WP MCP session (`SKILL.md` Step 1). Seed from the prepared catalog in
-`content-model.md`. **Idempotent by SKU** (products) and **code** (coupons) — list/search first, create
-only if absent, so a re-run never duplicates.
-
-1. **Product categories** — for each category: `wc-product-categories-list` (match by `slug`/`name`,
-   reuse the id) else `wc-product-categories-create { name, slug }`. Keep `name → id`.
-2. **Products** — for each product: `wc-products-search { sku: "<sku>" }`; a hit → reuse its id; empty →
-   `wc-products-create`:
-   ```json
-   { "name": "...", "type": "simple", "sku": "<unique>", "regular_price": "39.99",
-     "description": "...", "short_description": "...", "status": "publish",
-     "categories": [ { "id": <catId> } ] }
-   ```
-   - `regular_price` is a **decimal string in major units** (`"39.99"`) on the ability side — the Store
-     API re-exposes it as minor units to the storefront.
-   - **Variable products:** create the parent (`type: "variable"`) with its attributes, then the
-     variations (via the product update / variations ability that discovery lists).
-3. **Product images** — `media-upload-from-url { url, filename, alt_text, title }` (WordPress downloads
-   and stores its own copy; raster, HTTPS, direct file URL — source like the parent `SKILL.md` Unsplash
-   flow). Attach the returned media id to the product (`wc-products-update { id, images: [ { id } ] }`).
-   Idempotency: skip when the product already has images.
-4. **Coupons** — for each coupon: `wc-coupons-search { code }`; empty → `wc-coupons-create`:
-   ```json
-   { "code": "WELCOME10", "discount_type": "percent", "amount": "10" }
-   ```
-   (`discount_type`: `percent` | `fixed_cart` | `fixed_product`.)
-
-Record the SKU → id map, category ids and coupon codes into `content-model.md` under
-`## Created in WooCommerce` so the frontend and any re-run resolve references directly.
-
-**Verify over the public Store API (no auth):**
-- `GET {store_api}/products?per_page=100` → count matches the plan; each has `prices` (minor units +
-  `currency_minor_unit`) and, where seeded, an image.
-- `GET {store_api}/products/categories` → every planned category present.
-- Coupon: `wc-coupons-search { code }` returns it, or apply it to a throwaway cart and see the total drop.
+The push seeds the catalog with the rest of the content: put product categories, products and coupons
+under `store` in `content.json` and run `push-content.mjs` (`SKILL.md` Steps 1–2). It looks categories up
+by slug, products by **SKU** and coupons by **code** before creating, so a re-run never duplicates; uploads
+each product image once; checks every SKU and category over the Store API; and records the ids under
+`## Created in WooCommerce` in `content-model.md`.
+
+- `price` is a decimal string in **major units** (`"39.99"`); the Store API re-exposes it in minor units.
+- Any other WooCommerce product field passes through as given (`sale_price`, `stock_quantity`,
+  `attributes`, …). For a **variable product**, the push creates the parent; add its variations by hand
+  through the product update / variations ability that discovery lists.
+- Coupons: `discount_type` is `percent`, `fixed_cart` or `fixed_product`. WooCommerce stores codes in
+  lower case.
 
 ---
 
@@ -112,7 +87,7 @@ only writes standard WordPress settings (it ignores `woocommerce_*` options). So
 
 - **The catalog, product pages, client-side cart and coupon application all work headlessly.**
 - **Checkout (`POST /checkout`) does not work until the owner enables a payment method + a shipping zone
-  in wp-admin** (WooCommerce → Settings → Payments / Shipping; reach it via the one-click login in Step 9).
+  in wp-admin** (WooCommerce → Settings → Payments / Shipping; reach it via the one-click login in `steps/09-done/SKILL.md`).
   Cash on Delivery is the zero-config choice once enabled.
 - Treat this exactly like the Hostinger Ecommerce `payment_enabled: false` gate: record
   `woocommerce.payment_enabled: false`, tell the user in one line that checkout needs that one setup step,
@@ -144,10 +119,7 @@ through the per-site MCP and the storefront uses the public Store API. Document
 
 ## 6 — Idempotency & verification checklist
 
-- **Idempotency keys:** products → **SKU** (`wc-products-search { sku }`); coupons → **code**
-  (`wc-coupons-search { code }`); categories → **slug/name**; images → skip when the product already has
-  `images`.
-- **Verify over the public Store API** (no auth) — products count + prices + categories, and a coupon via
-  a cart apply. Record the id/SKU map into `content-model.md`.
-- **Checkout** is verified only when `payment_enabled` is `true`; while `false`, confirming the catalog +
-  cart over the Store API is the whole job.
+- **Idempotency keys:** products → SKU, coupons → code, categories → slug, images → skip when the product
+  already has `images`. `push-content.mjs` applies them; follow them too when seeding by hand.
+- **Checkout** is verified only when `payment_enabled` is `true`; while `false`, the catalog and cart over
+  the Store API are the whole job.

package/skills/headless/steps/05-design/SKILL.md

@@ -117,7 +117,7 @@ Before inventing anything, gather what already constrains the design:
 | Brand assets | `brief.md` → *Assets* | Logo, brand colours and fonts are **fixed** in every direction. Never recolour a supplied logo; Step 6 uses it instead of drawing an icon |
 | Pages and entities | `content-model.md` → *Navigation*, *Pages*, *Articles*; if it doesn't exist yet, `brief.md` → *Pages* | Drives the component inventory and page composition |
 | Reference sites | URLs in the brief or the conversation | Cues to borrow (see below) |
-| Images already sourced | `content-model.md` → the image lines under *Articles* (skip if none yet) | Glance at a few at small size; keep accents from clashing with their dominant colours |
+| Images already sourced | `content-model.md` → the image lines under *Articles*, or the `image` URLs in `content.json` on WordPress (skip if none yet) | Glance at a few at small size; keep accents from clashing with their dominant colours |
 | Current design (redesign only) | existing `design.md` | What to keep, what to move away from |
 
 **Reference sites.** Open each one in a real browser if you have one. Static fetches are often