docs(api,env): refresh API reference + .env.example for self-host onb…

[MrChengLen]

…oarding

Three connected fixes addressing the post-audit Doc-A findings (H5 api-reference.md staleness, M2 MAX_UPLOAD inconsistency) and the PM-Agent's R3 (.env.example structure). Aimed at making the Self-Hoster's first 30 minutes work without trial-and-error — a Technology-First / developer-discovery investment.

1. app/core/config.py — MAX_UPLOAD_SIZE_MB default 2000 → 100 MB

The .env.example, api-reference.md, and self-hosting.md all said the default was 100 MB; the code default was 2000 MB (2 GB). With zero real users yet, the canonical value can move freely. 100 MB is sane for unconfigured Self-Hosters (avoids OOM-by-default), matches the quota tiers in app/core/quotas.py for the anonymous tier, and tracks the docs that were already published. Operators with bigger payloads override via env-var.

2. .env.example — sectioned by deployment edition

Reorganised into four labelled sections so a self-hoster reading top-down hits only the keys their deployment needs:

• Required for every deployment (host/port, API_KEYS_FILE, MAX_UPLOAD, CORS, APP_BASE_URL, optional API_BASE_URL split)
• Cloud-overlay (JWT_SECRET, DATABASE_URL, Stripe, SMTP, PRICING_PAGE_ENABLED) — empty values keep features off
• Compliance-Edition tunables (AUDIT_FAIL_CLOSED, RETENTION_HOURS)
• Operational knobs (METRICS_ENABLED, sweep cadence, concurrency cap)

Variables that were missing from the example (JWT_SECRET, the Stripe keys, SMTP fields) are now visible as commented-out entries with purpose notes — a Self-Hoster who wants to enable accounts can see the exact set of env-vars to set without grep-hunting through code.

3. docs/api-reference.md — append, do not rewrite

Existing single-file structure preserved. Added:

• Authentication: explicit two-scheme table (X-API-Key for Community / scripts; Authorization: Bearer for Cloud overlay). Login / refresh examples for the JWT path.
• Cloud-Edition endpoints summary: /api/v1/auth/, /api/v1/keys, /api/v1/billing/ — each as a one-line entry with auth requirement and purpose. Avoids re-documenting schema; defers to the auto-generated Swagger UI at /docs for request bodies.
• Batch endpoints: /api/v1/convert/batch + /api/v1/compress/batch with their multipart shape and 200/422 semantics.
• Response Headers section: X-Output-SHA256 (every conversion), X-Data-Classification (BSI taxonomy echo), X-FileMorph-Achieved- Bytes / X-FileMorph-Final-Quality (target_size_kb path), Retry-After (503 path).
• Error Responses: added 403, 415, 503 with semantic notes.
• Rate Limiting table now includes /ready and the billing endpoints.

4. .githooks/pre-{commit,push} — allow .env.example

The hook's SECRET_ASSIGN regex correctly catches lines like JWT_SECRET=..., but .env.example is by definition the place to show those keys with placeholder values for self-hosters. Added \.env\.example to ALLOW_RE so legitimate documentation updates to that file aren't blocked.

Verified: 473 tests passing, ruff clean, drift-check unaffected.