# Site Builder Integration

## When to use

Use this skill when a task requires creating or inspecting a customer-facing marketing site, managing its content topic queue, generating blog drafts, or publishing pages through the Site Builder app (LLM-powered site generation, port 3062). Typical triggers: an ICP (ideal customer profile) submission needs a site provisioned, a GTM (go-to-market) agent needs to check or seed content topics, an auto-generated blog draft needs enqueuing, or a drafted page is ready to go live.

## Tools

- `http-get` — read site, topic, or page state.
- `http-post` — create sites, topics, or auto-post jobs.
- `http-request` — update or delete existing resources (PUT/PATCH/DELETE), such as amending a topic or removing a stale one.
- `write-file` — stage large result sets (for example a full topic list) before summarizing or handing off.
- `send-message` — escalate to a human when authentication fails or an Integration row is missing.

## Playbook

1. Before the first call, confirm the org has an active Site Builder Integration row configured with a base URL (e.g. `https://sitebuilder.newx.app/api/v1`). Do not ask the user for API keys — credentials are injected automatically by the Integration row.
2. To provision a new site from an ICP submission, use `http-post` against `/api/v1/sites`, passing the org, user, and `icp_submission_id`. This call is idempotent on `icp_submission_id`, so retries after a timeout are safe and will not create duplicate sites. This installs the template and enqueues the build.
3. To check what content is queued for a site, use `http-get` on `/api/v1/sites/:site_id/topics` to list topics ordered by priority. If the list is long, use `write-file` to stage it before summarizing back to the requester.
4. To add a manual content topic, use `http-post` against `/api/v1/sites/:site_id/topics` with `title`, `target_keyword`, and `notes`.
5. To have a blog draft generated for a queued topic, use `http-post` against `/api/v1/sites/:site_id/auto_posts`, optionally passing a specific `topic_id`; omit it to let Site Builder pick the next prioritized topic. This only enqueues generation — poll or re-check topics later to confirm the draft landed.
6. Once a page is reviewed and approved for release, use `http-post` against `/api/v1/pages/:id/publish` to make it live.
7. If any step needs to change or remove an existing resource (e.g. correcting a topic's keyword or retiring one), use `http-request` with the appropriate method against the resource's endpoint.

## Failure modes

- A 401 or 403 response means the Integration row's credentials are invalid, expired, or missing required scopes. Stop immediately — do not retry with guessed headers — and use `send-message` to alert a human, naming "Site Builder" and the scope needed (site creation, topic read/write, or publish).
- A missing Integration row for the org means Site Builder is not connected at all. Use `send-message` to ask a human to configure it before proceeding.
- A 422 or validation error on site creation usually means the `icp_submission_id` or org/user fields are malformed; do not retry blindly — report the payload issue via `send-message` if it cannot be corrected from available data.
- A stalled auto-post (topic never leaves queued state after enqueuing) should be reported rather than re-enqueued repeatedly, to avoid duplicate draft generation.

## Done when

The requested site exists (or was already idempotently present), the topic queue reflects the intended state, any requested auto-post has been enqueued and confirmed queued, and any page intended for release returns a successful response from `/api/v1/pages/:id/publish`. Any authentication or configuration blocker has been escalated via `send-message` rather than silently abandoned.