feat: enhance face-lock service with improved upload handling and response structure

- Updated README.md to reflect new features and API changes.
- Introduced versioning in app initialization.
- Enhanced configuration management in app/config.py with new validation functions.
- Refactored main.py to improve request handling and response generation.
- Added new models in app/models.py for structured API responses.
- Implemented a dedicated UI rendering function in app/ui.py.
- Improved Docker configuration for better security and health checks.
- Updated tests to cover new validation rules and response formats.
- Added CLAUDE.md for project guidelines and working rules.

docs/README.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-face-lock is a FastAPI service that detects a primary subject, makes a square crop, and returns both a crop and an annotated preview. The app ships with a simple Tailwind test UI at `/`.
+`face-lock` is a FastAPI service for square subject crops. It uses OpenCV-based
+detectors, returns stable JSON metadata for preview workflows, and can also
+stream the cropped JPEG directly for simple image pipelines.
 
 ## Endpoints
 
@@ -11,40 +13,64 @@ face-lock is a FastAPI service that detects a primary subject, makes a square cr
 - `POST /api/focus`
 - `POST /api/focus/image`
 - `GET /docs`
+- `GET /openapi.json`
 
-## Detectors
+## Detector modes
 
-- `face` for human faces
-- `animal` for pets / animals, with a contour fallback
-- `person` for full-body person detection
-- `subject` for general foreground subjects
+- `face` for frontal human faces
+- `animal` for pets and animals, with contour fallback
+- `person` for full-body people detection
+- `subject` for generic foreground contour detection
 
-## Test UI
+## Request validation
 
-Set `FACE_LOCK_TEST_UI=false` to disable the `/` test UI. If you update `.env`, recreate the container so Docker picks up the new values.
+- Uploads must be non-empty.
+- Uploads must stay below `FACE_LOCK_MAX_UPLOAD_BYTES`.
+- Content types must match `FACE_LOCK_ALLOWED_MIME_TYPES`.
+- `buffer_ratio` is clamped at the API layer to the `0.0` to `0.6` range.
 
 ## Authentication
 
-Set `FACE_LOCK_AUTH_TOKEN` to require a header token.
+Set `FACE_LOCK_AUTH_TOKEN` to require a shared secret.
 
-Supported headers:
+Supported forms:
 
 - `X-API-Key: <token>`
 - `Authorization: Bearer <token>`
 
 Optional override:
 
-- `FACE_LOCK_AUTH_HEADER` changes the expected header name.
+- `FACE_LOCK_AUTH_HEADER`
 
 ## Example
 
 ```bash
-curl -H 'X-API-Key: your-token' \
+curl \
+  -H 'X-API-Key: your-token' \
   -F 'file=@image.jpg' \
   -F 'detector=animal' \
+  -F 'buffer_ratio=0.2' \
   http://localhost:8000/api/focus
 ```
 
-## Docker note
+Binary crop response:
 
-Use `docker compose up -d --force-recreate` after env changes.
+```bash
+curl \
+  -H 'X-API-Key: your-token' \
+  -F 'file=@image.jpg' \
+  http://localhost:8000/api/focus/image \
+  --output crop.jpg
+```
+
+## Container notes
+
+- The production image runs as a non-root user.
+- The container includes a `/health` healthcheck.
+- Compose runs the root filesystem read-only and mounts `/tmp` as tmpfs.
+
+If you change `.env`, recreate the container:
+
+```bash
+docker compose up -d --force-recreate
+```