/03-provision

name: headless-step-provision
description: "Step 3 (provision) of the Hostinger Headless flow. Chooses the backend from brief.md (wordpress | ecommerce | webapp), then routes to the matching subfolder to provision it; writes site.json. WordPress + WooCommerce routes to the wordpress subfolder with the WooCommerce store turned on — it is not a separate backend."

headless-step-provision

Router. The backend is decided in **refine** and recorded in `brief.md`; this step only routes to the matching subfolder, which provisions it.

**In:** `brief.md`. **Out:** `site.json` (written by the subfolder).

**This stage runs in the background.** Provisioning is mostly a poll wait, so it splits in two: a **fire** half (detect + create, returns straight away) and a **join** half (poll to `completed`, verify, write `site.json`). Fire it, record `provision.in_progress`, then go do the prepare work of the other stages (content-model prepare, frontend shell) while it settles. Only cross back to the join half when an instance-barrier step needs the live backend. See *Background provision & the instance barrier* in the top-level `SKILL.md`. An agent that can't interleave simply does fire and join back-to-back — still correct, just no overlap.

Step 1 — Route on the suggested backend

Read the brief's **Suggested backend** section:

| Suggested backend | Follow | |---|---| | WordPress | `wordpress/SKILL.md` | | WordPress + WooCommerce | `wordpress/SKILL.md` **with the WooCommerce store on** (see below) | | Ecommerce | `ecommerce/SKILL.md` | | Webapp | `webapp/SKILL.md` |

If the section is missing or names something else, go back to **refine** — don't pick one here. Tell the user the backend and its one-line reason before provisioning.

> **WordPress + WooCommerce is the WordPress backend with a store — not a new backend.** Route it to > `wordpress/SKILL.md` and follow that recipe's **optional WooCommerce tail** (install + activate the > `woocommerce` plugin and verify the store endpoints; the catalog is seeded later through the per-site WP > MCP's native `wc-*` abilities — no custom plugin, no consumer key). `site.json → backend` stays > `"wordpress"`; the store is recorded under `site.json → woocommerce` (`enabled: true`). Everything else > downstream that routes on > `wordpress` (content-model push, deploy's `/cms` preservation, done's wp-admin login) then works > unchanged.

> **Supported backends: `wordpress` (optionally with a WooCommerce store), `ecommerce` and `webapp`.** > `webapp` is a plain Node.js app host (an empty website — no CMS, no store, no `/cms`) for any app/SPA > that brings its own code and data; it never installs WordPress. PocketBase is not available in this > version — refine never proposes it, and there is no `pocketbase/` subfolder; if a brief somehow names > it, stop and tell the user rather than improvising it. A **WordPress + Ecommerce** brief (two separate > backends — a WordPress site **and** a Hostinger Ecommerce store) has no single combined `start-setup` > type yet: stop, tell the user it isn't supported as one site, and offer either to continue with just > WordPress or just Ecommerce (route to that one subfolder), **or**, if they want content and a store on > **one** site, to switch the brief to **WordPress + WooCommerce** — the one-site path, which routes to > `wordpress/SKILL.md` with the store on.

Onboarding handoff — swap an existing empty headless shell (do this before creating anything)

Onboarding can create the website **before** you ever run, then paste the build prompt into this agent. When it does, the domain already has an **empty headless shell**: a website set up with `hosting_websites_start-setup { type: "headless_empty" }` — `website_type` is `headless`, but **nothing is installed** (no WordPress at `/cms`, no store). It is the hosting slot only, waiting for a backend.

So provision has **two entry shapes**, and each subfolder's *detect* step picks between them:

• **An empty headless shell already exists for the domain → adopt it and *swap* it to the chosen

backend. Never call `start-setup` again, never create a second site.** The swap is backend-specific:

• **WordPress** → install WordPress **into the existing shell's `/cms`** with

`wordpress_installations_install { type: "headless" }` (it rewrites the root `.htaccess` and marks the site headless-WordPress). Do **not** use `start-setup { type: "headless_wordpress" }` — that is only for creating a fresh site.

• **Ecommerce** → the empty headless shell **is** the storefront host already (a `headless_ecommerce`

website installs no store engine either). Adopt it as the frontend host and go straight to creating the store + custom sales channel.

• **No site exists for the domain at all → create it fresh, exactly as each subfolder defines today**

(`start-setup` with the backend's own `type`).

> **Webapp is not part of this handoff at all.** `webapp` is **not** reached on the usual onboarding > flow — it is only triggered by experimental actions — so it **ignores headless instances entirely**: > it never detects, adopts or swaps an empty headless shell, and provisions its own **Node.js app host** > exactly as `webapp/SKILL.md` defines today. The swap below is **WordPress and Ecommerce only**.

**How to tell an empty shell from an already-provisioned backend** (both read `website_type: headless`):

1. Exact-match the domain row in `hosting_websites_list` — if there is **no** row, nothing exists → create fresh. 2. Within 24 h of onboarding, `hosting_websites_list-setups` still shows the setup `type` (`headless_empty` = empty shell; `headless_wordpress` = WordPress already; `headless_ecommerce` = an ecommerce host). Beyond 24 h the setup drops off — fall back to the backend probe: 3. `wordpress_installations_list { username, domain, ownership: "all" }` — a row with `directory: "cms"` and `is_valid: true` means WordPress is **already** installed (adopt, don't sw