# AGENTS.md

Guide for AI agents integrating with **Domain Valet**.

## Product

**Domain Valet** tends idle domain portfolios. Users connect a registrar; we find names with no real site and auto-generate landing pages (waitlist, coming soon, for-sale, brand stub). Users approve before publish. We host on HTTPS.

**Tagline:** Your domains, tended.

**Audience:** domain investors, indie hackers, portfolio owners, agencies.

**Live URL:** https://valet.wntr.vc  
**Fallback:** https://parked-domains-production-73db.up.railway.app

**CLI name:** `valet` (e.g. `valet sync`, `valet build --idle`)

**Not in scope (yet):** full websites, domain transfers, marketplace/licensing, billing UI, OAuth for third-party agents.

## Platform direction (agentic)

Domain Valet is becoming an **agentic platform** for domain portfolios. Humans use the dashboard today; agents connect via API, MCP, or ChatGPT Actions.

**Planned integrations**

| Integration | Status | Purpose |
|-------------|--------|---------|
| Custom GPT (ChatGPT) | planned | Actions: list idle domains, draft pages, request publish |
| MCP tool server | planned | Claude/Cursor agents: sync registrar, build, publish with user approval |
| REST API | partial | `POST /api/waitlist` live; portfolio + publish endpoints TBD |
| `AGENTS.md` | live | This file, served at `/AGENTS.md` |

**Agent principles**

- Registrar access stays **read-only** until the user approves a publish (then scoped DNS write for that domain only).
- Agents **never** auto-publish without an explicit user approval step (per action or standing policy).
- All agent actions should be **idempotent** and **auditable** (log domain, action, outcome).

## Public HTTP API

Base URL: `https://valet.wntr.vc`

### `GET /api/health`

```json
{ "ok": "true" }
```

### `POST /api/waitlist`

Join the private-beta waitlist.

**Request** (`Content-Type: application/json`):

```json
{
  "email": "you@example.com",
  "registrar": "GoDaddy",
  "portfolio_size": "50 - 500 domains",
  "company": ""
}
```

| Field | Required | Notes |
|-------|----------|-------|
| `email` | yes | Valid email; stored lowercase; unique |
| `registrar` | yes | Non-empty string, max 120 chars |
| `portfolio_size` | yes | One of the allowed values below |
| `company` | no | Honeypot — if non-empty, returns fake success and does not store |

**Allowed `portfolio_size` values:**

- `1 - 50 domains`
- `50 - 500 domains`
- `500 - 5,000 domains`
- `5,000 - 50,000 domains`
- `50,000+ domains`

**Responses:**

| Status | Body | Meaning |
|--------|------|---------|
| 200 | `{ "status": "created" }` | New signup |
| 200 | `{ "status": "exists" }` | Email already on list |
| 200 | `{ "status": "ok" }` | Honeypot triggered |
| 400 | `{ "detail": "..." }` | Invalid portfolio size or registrar |
| 422 | validation error | Invalid email shape |
| 429 | `{ "detail": "..." }` | Rate limited (~8 req / 10 min per IP) |

**Example:**

```bash
curl -sS -X POST https://valet.wntr.vc/api/waitlist \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@test.example","registrar":"Cloudflare Registrar","portfolio_size":"1 - 50 domains"}'
```

There is **no admin API** to list waitlist entries.