@hostinger/mcp 3.2.2 → 3.3.0

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,100 @@
+---
+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`.
+
+All operations below go through the Hostinger connector (`execute`).
+
+> **Fire vs join (background provision).** Steps 1–2 up to `hosting_websites_start-setup` are the
+> **fire** half: after the setup is queued, record `provision.in_progress` and return to do prepare
+> work (see the router `../SKILL.md`). The readiness **poll** at the end of Step 2, plus Steps 3–4,
+> are the **join** half — run them when an instance-barrier step needs the backend (or immediately, if
+> the agent can't interleave). An already-`completed` site detected in Step 1 means provision is
+> already done: record `provision.completed` and adopt it.
+
+## Step 1 — Detect before you create (never provision twice)
+
+1. `hosting_websites_list { "domain": "<domain>" }` — substring filter, so **exact-match** the row's
+   `domain`. If a row exists, note `username`, `order_id`, `website_type`.
+2. `hosting_websites_list-setups { "domain": "<domain>" }` — exact-match the row:
+   - `completed` → already provisioned → skip to Step 3 (adopt it).
+   - `running` → skip to Step 2 (poll).
+   - `failed` → tell the user and point them at hPanel; do **not** call start-setup again on your own.
+3. If the site exists but `website_type` is not `headless`, stop and tell the user — this domain
+   already hosts a different kind of site.
+
+## Step 2 — Create (only when nothing exists)
+
+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 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 — Record `site.json`
+
+```json
+{
+  "backend": "wordpress",
+  "website_type": "headless",
+  "order_id": 1007223428,
+  "username": "u…",
+  "wordpress": {
+    "install_id": "30…",
+    "directory": "cms",
+    "admin_login": "…"
+  },
+  "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.

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

@@ -0,0 +1,150 @@
+---
+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 (generated into media/, or sourced from Unsplash — see *Images* below) with
+> alt text. Omit if the brief has no article-like content.
+
+## Products (optional — required for a commerce brief)
+> Skip for a non-commerce brief. For a commerce brief, generate the catalog content here (prepare
+> work, no instance): for each product — name, slug, SKU, short + long description in the brief's
+> tone, price, the collection it belongs to, variants if any, and a product image (generated into
+> media/, or sourced from Unsplash — see *Images*) with alt text. Group products into the collections
+> the brief implies. The `ecommerce` push phase creates these on the store's sales channel.
+```
+
+Guidance:
+
+- **Fixed vs. prompt.** Title and Description are concrete values. Navigation, Pages and Articles are
+  prompts because their volume/wording is generated — keep them as prompts so the push phase (or a
+  rerun) can regenerate consistently.
+- **Run the prompts now.** Generate the actual page copy, article drafts and images during the wait —
+  this is the slowest work and the whole reason it runs in parallel. Put generated media in
+  `~/.hostinger/<domain>/media/` and reference it by filename. Record Unsplash images by URL (see
+  *Images* below). Record alt text for every image.
+- **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 — source from Unsplash when you can't generate them
+
+Every article needs a featured image. If you can generate images, put them in `media/`. If you
+can't (most coding agents can't), source real photos from Unsplash. This is still prepare work and
+needs no live backend: you only pick the photos and record their URLs here. The push phase uploads
+them.
+
+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` |
+| Ecommerce | `ecommerce/SKILL.md` |
+| Webapp | — (no push; skip to frontend) |
+
+> **Supported backends: `wordpress`, `ecommerce`, and `webapp`** — where `webapp` is "supported" by
+> **skipping this whole stage** (it has no content backend; see the note below). PocketBase is not
+> available in this version. Push to whichever single backend provision set up (see the provision
+> router) — don't try to push to two backends here.
+>
+> **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.