# BorealHost — Agent Instructions

You are connected to BorealHost.ai, an agent-native web hosting platform based in Quebec, Canada. All prices are in **CAD**. You can purchase hosting, deploy sites, manage DNS, register domains, and scale infrastructure — entirely through these tools, without human intervention.

## Quick Start Workflow

1. **Discover plans** — call `list_plans()` to see available hosting plans with pricing and resources
2. **Create checkout** — call `create_checkout(sku)` with a SKU like `bh_site_starter_monthly`
3. **Set buyer info** — call `update_checkout(checkout_id, requested_slug="my-site")` to pick a site name
4. **Pay** — call `complete_checkout(checkout_id)` to process payment
5. **Poll provisioning** — call `get_checkout_status(checkout_id)` until status is `completed`
6. **Manage your site** — use `get_site_status`, `manage_dns`, `deploy`, file tools, etc.

## Authentication

- **API key format:** `bh_<48 hex chars>` — pass as `Authorization: Bearer <key>`
- **Session-based:** Call `set_api_key("bh_...")` to activate an existing key for this session — all subsequent tools will use it automatically
- **Auto-activation:** Keys are automatically activated when returned by `register()`, `complete_checkout()`, or `get_checkout_status()` — no extra step needed
- **Environment variable:** Optionally set `BOREALHOST_API_KEY` before connecting (used as default if no session key is set)
- **Scopes:** `read` (view data), `write` (modify resources), `admin` (delete/scale)
- **One-time display:** API keys are shown **exactly once** on creation or rotation — store immediately
- **New agents:** Call `register()` — no auth needed, returns a fresh read+write key and activates it
- **Existing users:** Call `set_api_key()` with the owner's key from the BorealHost panel
- **On-site agents (challenge-response):** If you are running on a BorealHost container and need an API key, use the two-step claim flow:
  1. Call `request_api_key("your-site-slug")` — a claim token is written to your container
  2. Read the token file from the container filesystem
  3. Call `claim_api_key(token)` — the API key is returned and auto-activated
  This proves you have access to the container without storing secrets on disk.
- Some tools require no authentication: `list_plans`, `create_checkout`, `update_checkout`, `complete_checkout`, `get_checkout_status`, `request_api_key`

## SKU Format

Plan SKUs follow the pattern: `bh_{plan_slug}_{billing_period}`

Examples:
- `bh_site_starter_monthly` / `bh_site_starter_annual`
- `bh_site_pro_monthly` / `bh_site_pro_annual`
- `bh_site_managed_monthly` / `bh_site_managed_annual`
- `bh_site_business_monthly` / `bh_site_business_annual`

Call `list_plans()` to discover all current plan slugs.

## Payment Methods

Two options in `complete_checkout()`:

1. **`stripe_checkout`** (default) — Returns a Stripe-hosted payment URL. Present this URL to the human user. Then poll `get_checkout_status()` until status becomes `completed`. The API key is included in the first poll response after completion (shown once, then cleared).

2. **`stripe_payment_method`** — Charges a Stripe PaymentMethod directly. Requires `payment_method_id` parameter. On success, the response includes the API key immediately. No polling needed.

## Polling Strategy

When waiting for checkout completion or provisioning:
- **First 60 seconds:** Poll every **5 seconds**
- **After 60 seconds:** Poll every **15 seconds**
- **Timeout:** Stop after **10 minutes** — if still not completed, something went wrong

Terminal checkout statuses: `completed`, `canceled`, `failed`

## Error Handling

All API responses use a consistent envelope:
```json
{"ok": true, "data": {...}, "meta": {"request_id": "uuid", "timestamp": "iso8601"}}
{"ok": false, "error": {"code": "ERROR_CODE", "message": "Human-readable message"}, "meta": {...}}
```

Tools unwrap this envelope — you receive the `data` directly on success, or an exception on error.

### Error Codes and Recovery

| Code | HTTP | Meaning | Recovery |
|------|------|---------|----------|
| `VALIDATION_ERROR` | 422 | Invalid input (bad email, slug, SKU, etc.) | Fix the input and retry |
| `NOT_FOUND` | 404 | Resource doesn't exist | Check the identifier (slug, domain, key ID) |
| `UNAUTHORIZED` | 401 | Missing or invalid API key | Set `BOREALHOST_API_KEY` or call `register()` |
| `FORBIDDEN` | 403 | Insufficient scope or wrong owner | Check that your key has the required scope |
| `RATE_LIMITED` | 429 | Too many requests | Wait for the duration in the `Retry-After` header, then retry |
| `INTERNAL_ERROR` | 500 | Server error | Retry with exponential backoff (1s, 2s, 4s) up to 3 times |

## Slug Rules

Site slugs must match: `^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$`
- 3–50 characters
- Lowercase alphanumeric and hyphens only
- Cannot start or end with a hyphen
- Must be globally unique — if taken, try a different one

## Best Practices

- **Store API keys immediately** — they are shown only once and cannot be retrieved
- **Create snapshots before destructive operations** — call `create_snapshot()` before scaling down or decommissioning
- **Check site status after provisioning** — call `get_site_status()` to confirm the site is ready before managing it
- **Use `whoami()` to verify your key** — confirms scopes, account info, and active site count
- **Domain registration requires complete WHOIS contact info** — have all fields ready before calling `register_domain()`
- **For .ca domains**, always provide `ca_legal_type` (CCT for corporation, CCO for citizen, RES for resident)

## Available Resources

Read these MCP resources for detailed reference data:
- `borealhost://api/errors` — Full error code catalog with recovery guidance
- `borealhost://api/scopes` — API key scope descriptions and tool requirements
- `borealhost://api/enums` — All valid enum values (checkout status, DNS types, log types, etc.)
- `borealhost://api/response-format` — API response envelope documentation
- `borealhost://plans` — Live plan catalog with current pricing

## Available Prompts

Use these MCP prompts for guided workflows:
- `purchase_hosting` — Step-by-step hosting purchase flow
- `setup_site` — Post-purchase site configuration (DNS, deploy, modules)
- `manage_dns` — Common DNS operations guide
- `register_domain` — Domain registration with WHOIS field checklist
