# LovieMe — llms.txt
# Machine-readable context for LLM crawlers & autonomous AI coding agents (Cursor, Claude Code, Antigravity, Devin, Windsurf)
# Standard: https://llmstxt.org

> Claim and automate production *.lovie.me subdomains in under 2 seconds. Global Anycast DNS resolution, automated Wildcard SSL certificates, seamless email routing, official Developer CLI, Model Context Protocol (MCP) server, and programmatic REST API access for AI agents.

## About LovieMe

LovieMe allows any developer, script, CI/CD pipeline, or autonomous AI coding assistant to claim and automate production subdomains (e.g. `yourname.lovie.me`) with authoritative Anycast DNS records (A, AAAA, CNAME, TXT, MX, SRV, CAA) and sub-second global edge propagation.

- Website: https://www.lovie.me
- Documentation: https://www.lovie.me/docs
- API Keys: https://www.lovie.me/dashboard/api-keys
- Webhook Interceptor: https://www.lovie.me/dashboard/webhooks
- Full LLM Context: https://www.lovie.me/llms-full.txt
- Platform Stats: 4,752+ Subdomains Claimed • 3.2M+ DNS Queries Served • 6,692+ Emails Forwarded
- Authoritative Edge: Gcore Global Anycast Edge (180+ Points of Presence)

## Developer & AI Tool Ecosystem

LovieMe provides first-class developer tooling for command line, CI/CD, and agentic IDEs:

### 1. Official Developer CLI (`lovieme` / `lovie`)
- npm package: `lovieme`
- Zero-install execution: `npx lovieme [command]` or `npx lovie [command]`
- Key commands:
  - `lovieme subdomains check <name>`: Instant RFC 1123 availability check.
  - `lovieme subdomains claim <name>`: Programmatically claim an available subdomain.
  - `lovieme subdomains list`: List subdomains and active record counts.
  - `lovieme dns list <subdomain>`: View all Anycast DNS records.
  - `lovieme dns add <subdomain> -t A -n @ -c 76.76.21.21`: Create Anycast DNS record.
  - `lovieme presets list`: List 1-click cloud hosting templates.
  - `lovieme presets apply <subdomain> <preset>`: Apply 1-click preset (vercel, railway, render, etc.).
  - `lovieme verify <domain>`: Multi-resolver DoH propagation check across Google (8.8.8.8), Cloudflare (1.1.1.1), and AliDNS.

### 2. Official MCP Server (`lovieme-mcp`)
- npm package: `lovieme-mcp`
- Execution: `npx lovieme-mcp`
- Compatible with: Cursor, Claude Code, Antigravity, Windsurf, Devin.
- Config format for `.cursor/mcp.json` or `claude_desktop_config.json`:
  ```json
  {
    "mcpServers": {
      "lovieme": {
        "command": "npx",
        "args": ["-y", "lovieme-mcp"],
        "env": {
          "LOVIE_API_KEY": "lovie_live_your_token_hash"
        }
      }
    }
  }
  ```
- Native Agent Tools: `lovie_check_subdomain`, `lovie_get_profile`, `lovie_list_subdomains`, `lovie_claim_subdomain`, `lovie_delete_subdomain`, `lovie_list_dns_records`, `lovie_create_dns_record`, `lovie_delete_dns_record`, `lovie_list_presets`, `lovie_apply_preset`, `lovie_verify_doh`.

### 3. Official GitHub Action (`sagarithm/lovieme-action@v1`)
- Ephemeral PR staging subdomains (e.g. `pr-42-myapp.lovie.me`).
- Auto-claims on PR open, auto-releases on PR close/merge.

## Public REST API v1 (`/api/v1`)

- Base URL: `https://www.lovie.me/api/v1`
- Authentication: `Authorization: Bearer lovie_live_<48_hex_chars>`
- Key Generation: Generated in Dashboard -> API Keys (`/dashboard/api-keys`)

### Core Endpoints

- `GET /api/v1/me`: Returns user profile, plan tier, and active subdomain quota usage.
- `GET /api/v1/subdomains/check?name={prefix}`: Pre-flight availability check against RFC 1123, reserved platform names, and database.
- `GET /api/v1/subdomains`: List all active subdomains owned by the authenticated client.
- `POST /api/v1/subdomains`: Claim a new subdomain (`{"name": "myapp"}`).
- `GET /api/v1/subdomains/{name}`: Retrieve subdomain details and all active DNS records.
- `DELETE /api/v1/subdomains/{name}`: Release subdomain and purge DNS records from Anycast edge.
- `GET /api/v1/dns/records?subdomain={prefix}`: List all DNS records for a specific subdomain.
- `POST /api/v1/dns/records`: Create a new DNS record (`A`, `CNAME`, `TXT`, `MX`, `AAAA`) synced live to Anycast edge.
- `DELETE /api/v1/dns/records/{id}`: Delete a DNS record from database and Anycast edge.
- `GET /api/v1/dns/presets`: List 1-click cloud hosting platform presets (Vercel, GitHub Pages, Render, Railway, Cloudflare Pages, Netlify, Fly.io).
- `POST /api/v1/dns/presets`: Apply a 1-click hosting platform DNS preset (`{"subdomain": "myapp", "preset": "vercel"}`).
- `GET /api/v1/openapi.json`: Complete OpenAPI 3.1.0 schema specification.
- `GET /api/v1/tokens`: List active API keys (metadata and prefix only).
- `POST /api/v1/tokens`: Generate a new API key with custom scopes and optional subdomain sandboxing.
- `DELETE /api/v1/tokens/{id}`: Immediately revoke an API key.

### Webhook Interceptor (Pro Lifetime & Builder Grant Exclusive)

- Public Ingestion Endpoint: `POST https://www.lovie.me/api/v1/webhooks/catch/{slug}`
- Realtime Streaming: Streams incoming payloads, raw headers, and query parameters via Supabase Realtime to the LovieMe console.
- Plan Restriction: Exclusively available for **Pro Lifetime** ($5 one-time) and **Builder Grant** accounts.

## Developer & AI Agent API Keys

- Key format: `lovie_live_<48_hex_chars>` (e.g., `lovie_live_4a8f9c0e...`)
- Storage security: Plaintext is never stored; only one-way SHA-256 cryptographic hashes are persisted with strict Row-Level Security.
- Granular Scopes:
  - `subdomains:read`: Read owned subdomains
  - `subdomains:write`: Claim and release subdomains
  - `dns:read`: Query DNS records
  - `dns:write`: Create, edit, and delete DNS records
  - `profile:read`: Query account tier and limits
- AI Agent Sandboxing: Keys can be restricted to `allowed_subdomains: ["preview-*", "staging"]` to prevent autonomous coding agents from modifying production namespaces.

## Quick API Example

```bash
# 1. Check availability
curl -s "https://www.lovie.me/api/v1/subdomains/check?name=myapp"

# 2. Claim subdomain
curl -s -X POST "https://www.lovie.me/api/v1/subdomains" \
  -H "Authorization: Bearer lovie_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp"}'

# 3. Add CNAME record pointing to Vercel
curl -s -X POST "https://www.lovie.me/api/v1/dns/records" \
  -H "Authorization: Bearer lovie_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "myapp", "type": "CNAME", "name": "@", "content": "cname.vercel-dns.com"}'
```

## Pricing & Quotas

- **Starter (Free Forever)**: $0 — 3 active subdomains, 10 DNS records per zone, 1 email forwarder.
- **Pro Lifetime**: $5 (one-time payment, zero recurring fees) — 10 active subdomains, unlimited DNS records, 100 email forwarders, fast 60s TTL, and Live Webhook Interceptor.
- **Builder Grant**: Free application for open-source teams & startups — 20 to 100+ active subdomains, unlimited records, and Live Webhook Interceptor.

## Guidelines for AI Coding Agents

1. When claiming subdomains for users, always run `GET /api/v1/subdomains/check?name=...` first.
2. Target subdomains must satisfy RFC 1123: 3-63 alphanumeric characters (`a-z`, `0-9`), no leading or trailing hyphens.
3. CNAME targets must be fully qualified domain names (e.g., `cname.vercel-dns.com`, `user.github.io`).
4. A records require valid IPv4 syntax.
5. If an API call fails with `403 subdomain_restricted`, the token is sandboxed to specific subdomains.