# xTerminal site setup

Skill-Id: setup-site
Skill-Version: 1
Canonical: https://www.xterminal.dev/xterminal/skills/setup-site/v1

The person just connected one xTerminal site. They will say **Set up my xTerminal site**. Follow this checklist. Do not invent GitHub or Vercel tokens inside xTerminal. Use the connectors already on this agent. Steps are idempotent. Resume from the first step that is not done.

xTerminal does not call GitHub or Vercel. You do.

## Auth for Runtime

Call `https://www.xterminal.dev/api/developer/v1/runtime-keys` as the signed-in admin or developer. Cookie session or Bearer user JWT. Never a worker key. Never a Runtime key as the Authorization header. Set `x-xt-tenant-slug` to the approved site slug when you have it.

## Checklist

### 1. Confirm GitHub and Vercel connectors

Confirm this agent can create a repo on the person's GitHub and a project on their Vercel. If either connector is missing, stop. Tell them what broke, what to click, and what to say to retry.

### 2. Confirm xTerminal auth and Runtime

GET `https://www.xterminal.dev/api/developer/v1/runtime-keys`. You should see the tenant slug and whether an active key exists. Then POST `https://www.xterminal.dev/api/developer/v1/runtime-keys` with:

```json
{ "name": "Client site runtime key", "reuse": true }
```

`reuse` defaults true. If the response includes `raw_key`, keep it only long enough to write Vercel env. If `minted` is false and `raw_key` is null, an active key with that name already exists. POST once more with a distinct name so you receive the secret once:

```json
{ "name": "Site template runtime key", "reuse": true }
```

Do not print the raw key back to the person unless they ask. Owners cannot mint. Worker keys cannot mint.

Env values from a successful POST or GET:

- `NEXT_PUBLIC_XT_TENANT_SLUG`
- `NEXT_PUBLIC_XT_API_BASE_URL`
- `XT_BACKEND_CONTACT_ENDPOINT`
- `NEXT_PUBLIC_XT_PUBLIC_API_KEY`

Write `NEXT_PUBLIC_XT_PUBLIC_API_KEY` only when you have `raw_key`. The other three lines come from the JSON `env` object even on reuse.

### 3. Create or reuse the repo

Create a repo from the public template `Windborne-Creative/xterminal-site-template` (https://github.com/Windborne-Creative/xterminal-site-template). If a repo from that template already exists for this person, reuse it. If the name collides, reuse the template lineage or ask once for a rename.

### 4. Create or link the Vercel project

Create a Vercel project from that repo, or link the existing project. If the team is ambiguous, ask once which team. Do not create a second project when one already points at this repo.

### 5. Upsert env

Write the four env keys onto the Vercel project (production). Do not commit secrets to the repo. If env write is denied, stop and tell them which permission to grant.

### 6. Deploy production

Trigger a production deploy. Wait until it finishes. If the build fails, give them the build log URL, the error summary, and what to say to retry.

### 7. Verify the Runtime path

Hit a public Runtime read on the live host (blog or another dynamic path that uses the key). If it fails, re-upsert env and redeploy once. If it still fails, stop. Tell them what broke.

### 8. Report live URL, repo, and project

When production is up, report the live URL, the GitHub repo, and the Vercel project. Then stop.

## Failure copy

Every stop uses the same shape: what broke, what to click, what to say to retry. Suggested retries:

| Break | What to click | What to say |
| --- | --- | --- |
| No GitHub on this agent | Connect GitHub in the agent | Set up my xTerminal site |
| No Vercel on this agent | Connect Vercel in the agent | Set up my xTerminal site |
| xTerminal auth or Runtime failed | Reconnect at https://www.xterminal.dev/admin/mcp/connected or regenerate Runtime | Set up my xTerminal site |
| Repo name collision | Reuse the existing template repo, or rename once | Resume setup |
| Wrong Vercel team | Pick the team, then continue | Resume setup |
| Env write denied | Grant project env permission | Resume setup |
| Deploy failed | Open the build log, fix, redeploy | Resume setup |
| Runtime verify failed | Re-upsert env, redeploy once | Resume setup |
| MCP disconnected mid-flight | Reconnect, then return here | Resume setup |

Resume means fetch https://www.xterminal.dev/xterminal/skills/setup-site/v1 again and start at the first unfinished step. Do not redo a step that already succeeded.

## Out of scope

Do not mint worker keys. Do not save a wake webhook. Do not ask xTerminal to call GitHub or Vercel. Docs wizard parity is a later path. This skill is the agent door.

Docs: https://www.xterminal.dev/xterminal/docs/connect-an-agent-mcp