# Agent Instructions for DocMint

## Site Overview

DocMint is a professional PDF generation platform. Users create PDF documents (CVs, invoices, contracts, letters, reports) from 56+ templates via a web editor or a REST API.
URL: https://docmint.xyz

## Publicly Accessible Content (Agent-Friendly)

- **Home**: `/` — Product overview, features, pricing summary
- **Templates**: `/templates` — PDF template gallery (56+ templates, 9 categories)
- **Template creation pages**: `/create/{template-id}` — e.g. `/create/invoice`, `/create/cv`
- **Pricing**: `/pricing` — Free ($0), Pro ($9/mo), Business ($29/mo) plans
- **Documentation**: `/docs` — REST API reference and integration guides
- **Blog**: `/blog` — Technical articles and tutorials
- **Legal**: `/privacy`, `/terms` — Policies

## Auth-Gated Content (Not Agent-Accessible)

- **Dashboard**: `/dashboard` — User workspace
- **Billing**: `/dashboard/billing` — Subscription management
- **API Keys**: `/dashboard/api-keys` — API key generation/management
- **Settings**: `/dashboard/settings` — User preferences

## Agent-Friendly Features

- **Markdown versions**: Append `.md` to any public URL (e.g., `/templates.md`, `/pricing.md`)
- **Content negotiation**: Send `Accept: text/markdown` header to receive markdown
- **Structured data**: JSON-LD on every page (schema.org: WebApplication, Organization, ItemList, Product, FAQPage)
- **Discovery index**: `/llms.txt` for the complete documentation index
- **Markdown sitemap**: `/sitemap.md` — semantic sitemap with descriptions
- **Capability manifest**: `/.well-known/agent-skills/index.json`

## Authentication

- **Public content**: No auth required
- **Protected routes**: Custom JWT session cookies (human browser sessions)
- **API access**: Personal API keys via `x-api-key` header (generate in dashboard at `/dashboard/api-keys`, requires Pro plan or higher)

## API Quick Start

```bash
# Generate a PDF programmatically (requires Pro/Business API key)
curl -X POST https://api.docmint.xyz/api/v2/pdf \
  -H "Content-Type: application/json" \
  -H "x-api-key: dm_YOUR_KEY_ID_YOUR_SECRET" \
  -d '{"templateId": "invoice", "data": {"companyName": "Acme Corp"}}'
```

Response errors are typed JSON with machine-readable codes (`INVALID_API_KEY`, `ENTITLEMENT_REQUIRED`, `RATE_LIMITED`, `MONTHLY_LIMIT_REACHED`) and include `Retry-After` headers when rate limited.

## Rate Limits

- **Public pages**: Standard web rate limits per IP
- **Auth endpoints**: 10 requests/minute per IP
- **API endpoints** (`/api/v2/pdf`): Per-key limits by plan (Pro: 60/min, Business: higher) + monthly quotas (Pro: 10,000/mo, Business: 100,000/mo)

## Error Handling for Agents

All API endpoints return typed errors:

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retryable": true
  }
}
```

Rate-limited responses include a `Retry-After` header with seconds.

## MCP Server

Not currently available. Use direct HTTP access with the REST API above.