feat(maturity): add dedicated NSFW/maturity analysis service

- Add maturity/ service (FastAPI + Falconsai/nsfw_image_detection ViT classifier)
  - /analyze (URL) and /analyze/file (multipart upload) endpoints
  - Normalized response: maturity_label, confidence, score, labels,
    action_hint (safe/review/flag_high), advisory, threshold_used,
    analysis_time_ms, model, source
  - Configurable thresholds via MATURITY_THRESHOLD_MATURE / MATURITY_THRESHOLD_REVIEW
  - Reuses common/image_io for URL validation and file-size enforcement
  - Explicit 502/503 errors on failure — no silent safe fallback
  - Per-request structured logging (score, label, threshold path, elapsed ms)

- Update gateway/main.py
  - MATURITY_URL + MATURITY_ENABLED env vars
  - POST /analyze/maturity and POST /analyze/maturity/file endpoints
  - /health includes maturity service status
  - _assert_maturity_enabled() guard for clean 503 when disabled
  - All existing endpoints untouched (additive change)

- Update docker-compose.yml
  - Add maturity service with healthcheck (start_period: 90s)
  - Gateway environment: MATURITY_URL, MATURITY_ENABLED
  - Gateway depends_on: maturity (service_healthy)

- Update README.md and USAGE.md
  - Document maturity service, env vars, curl examples,
    full response schema table, action_hint logic, failure guidance

README.md

@@ -1,6 +1,6 @@
-# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant + Card Renderer) – Dockerized FastAPI
+# Skinbase Vision Stack (CLIP + BLIP + YOLO + Qdrant + Card Renderer + Maturity) – Dockerized FastAPI
 
-This repository provides **five standalone vision services** (CLIP / BLIP / YOLO / Qdrant / Card Renderer)
+This repository provides **six standalone vision services** (CLIP / BLIP / YOLO / Qdrant / Card Renderer / Maturity)
 and a **Gateway API** that can call them individually or together.
 
 ## Services & Ports
@@ -12,6 +12,7 @@ and a **Gateway API** that can call them individually or together.
 - `qdrant`: vector DB (port `6333` exposed for direct access)
 - `qdrant-svc`: internal Qdrant API wrapper
 - `card-renderer`: internal card rendering service
+- `maturity`: internal NSFW/maturity classifier service
 
 ## Run
 
@@ -30,6 +31,15 @@ HUGGINGFACE_TOKEN=your_huggingface_token_here
 
 `HUGGINGFACE_TOKEN` is required when the configured BLIP model is private, gated, or otherwise requires Hugging Face authentication.
 
+Optional maturity configuration (override in `.env` if needed):
+
+```bash
+MATURITY_MODEL=Falconsai/nsfw_image_detection
+MATURITY_THRESHOLD_MATURE=0.80
+MATURITY_THRESHOLD_REVIEW=0.60
+MATURITY_ENABLED=true
+```
+
 Service startup now waits on container healthchecks, so first boot may take longer while models finish loading.
 
 ## Health
@@ -96,6 +106,41 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/analyze/yo
   -F "conf=0.25"
 ```
 
+## Maturity / NSFW analysis
+
+Analyzes an image and returns a normalized maturity signal for Nova moderation workflows.
+
+### Analyze by URL
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/analyze/maturity \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://files.skinbase.org/img/aa/bb/cc/md.webp"}'
+```
+
+### Analyze from file upload
+```bash
+curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/analyze/maturity/file \
+  -F "file=@/path/to/image.webp"
+```
+
+Example response:
+```json
+{
+  "maturity_label": "mature",
+  "confidence": 0.94,
+  "score": 0.94,
+  "labels": ["nsfw"],
+  "model": "Falconsai/nsfw_image_detection",
+  "threshold_used": 0.80,
+  "analysis_time_ms": 183.0,
+  "source": "maturity-service",
+  "action_hint": "flag_high",
+  "advisory": "High-confidence mature content detected"
+}
+```
+
+`action_hint` values: `safe`, `review`, `flag_high`. Nova should use these to decide blur/queue/flag behaviour.
+
 ## Vector DB (Qdrant) via gateway
 
 Qdrant point IDs must be either:
@@ -228,8 +273,9 @@ curl -H "X-API-Key: <your-api-key>" -X POST https://vision.klevze.net/cards/rend
 
 ## Notes
 
-- This is a **starter scaffold**. Models are loaded at service startup.
+- Models are loaded at service startup; initial container start can take 1–2 minutes as model weights are downloaded.
 - Qdrant data is persisted in the project folder at `./data/qdrant`, so it survives container restarts and recreates.
 - Remote image URLs are restricted to public `http`/`https` hosts. Localhost, private IP ranges, and non-image content types are rejected.
+- The maturity service uses `Falconsai/nsfw_image_detection` (ViT-based). Thresholds are configurable via `.env`. The model handles photos and stylized digital art but should be calibrated against real Skinbase content before production use.
 - For production: add auth, rate limits, and restrict gateway exposure (private network).
 - GPU: you can add NVIDIA runtime later (compose profiles) if needed.