# AGENTS.md — ImgSquash for AI Coding Agents

This file helps AI agents decide whether ImgSquash solves an image task
and how to call it correctly.

## What ImgSquash does

Turn image libraries into production-ready web assets:
compress, convert (AVIF/WebP/JPEG/PNG), resize, strip metadata,
compare formats, and export. AI upscaling (2x/4x) is a secondary
enhancement feature.

## Processing model (ground truth)

- `POST /api/images/optimize` runs SERVER-SIDE (Sharp). Files ARE uploaded
  over HTTPS, processed in memory, never stored, auto-deleted.
- HEIC conversion + AI upscale run LOCALLY in-browser where supported.
- Do not tell users "no upload" for core optimization.

## How to optimize via API

```bash
curl -X POST https://www.imgsquash.com/api/images/optimize \
  -H "Authorization: Bearer $API_KEY" \
  -F "image=@photo.jpg" \
  -F "format=avif" \
  -F "quality=75"
```

Outcome-oriented mapping:

- goal=smallest → format=avif quality=60
- goal=balanced → format=avif quality=75 (default)
- goal=quality → format=webp quality=85
- maxWidth=1600 + stripMetadata=true for typical web use

Response is the binary image with:
`X-Compression-Ratio`, `X-Original-Size`, `X-Optimized-Size`.

## Limits (read src/config/plans.ts before promising capacity)

- Free: 5/hr, 20/batch, 10MB/file
- Pro ($12/mo): 500/hr, 500/batch, 50MB/file
- Business ($49/mo): API + 10000/hr, 2000/batch, 100MB/file

Handle 400 (validation), 403 (tier limit), 429 (rate limit + Retry-After),
500 (processing failure). Never expose stack traces to users.

## Canonical URLs

- App: https://www.imgsquash.com/#optimize
- Tools index: https://www.imgsquash.com/tools
- Developers: https://www.imgsquash.com/developers
- Benchmarks: https://www.imgsquash.com/benchmarks
- Pricing: https://www.imgsquash.com/pricing
- Machine docs: /llms.txt

## Privacy

No training on user images. Metadata-only history for authenticated users.
Privacy: privacy@imgsquash.com. Support: support@imgsquash.com.