API: Standardized JSON list responses with Pydantic schemas and Pagination; add sort_by/sort_dir validation with whitelists; consistent JSON 401 for /api/*; structured logging for sorting/pagination; add pydantic dep; add Docker smoke script and README docs.

README.md

@@ -82,6 +82,39 @@ curl http://localhost:8000/health
 
 4. Access the API at `http://localhost:8000`
 
+## API JSON Lists and Sorting
+
+The following list endpoints return standardized JSON with a shared `pagination` envelope and Pydantic models:
+
+- `GET /api/rolodex` → items: `ClientOut[]`
+- `GET /api/files` → items: `CaseOut[]`
+- `GET /api/ledger` → items: `TransactionOut[]`
+
+Common query params:
+- `page` (>=1), `page_size` (1..100 or 200 for ledger)
+- `sort_by` (endpoint-specific whitelist)
+- `sort_dir` (`asc` | `desc`)
+
+If `sort_by` is invalid or `sort_dir` is not one of `asc|desc`, the API returns `400` with details. Dates are ISO-8601 strings, and nulls are preserved as `null`.
+
+Authentication: Unauthenticated requests to `/api/*` return a JSON `401` with `{ "detail": "Unauthorized" }`.
+
+### Sorting whitelists
+- `/api/rolodex`: `id, rolodex_id, last_name, first_name, company, created_at`
+- `/api/files`: `file_no, status, case_type, description, open_date, close_date, created_at, client_last_name, client_first_name, client_company, id`
+- `/api/ledger`: `transaction_date, item_no, id, amount, billed, t_code, t_type_l, employee_number, case_file_no, case_id`
+
+## Docker smoke script
+
+A simple curl-based smoke script is available:
+
+```bash
+docker compose up -d --build
+docker compose exec delphi-db bash -lc "bash scripts/smoke.sh"
+```
+
+Note: For authenticated API calls, log in at `/login` via the browser to create a session cookie, then copy your session cookie to a `cookies.txt` file for curl usage.
+
 ## Project Structure
 
 ```