chore(release): bump version to 1.7.0

- Increment version from 1.6.0 to 1.7.0 in package.json
- Add detailed CHANGELOG.md entry for Swagger UI & OpenAPI 3.1 documentation
- Update README.md version highlight to mention Swagger UI
- Add API Documentation System section (7.4) to ARCHITECTURE.md
- Add swagger-ui-express, swagger-jsdoc, yamljs, spectral-cli to Technology Stack
- Update High-Level Architecture diagram with Swagger UI node
- Update Request routing summary to include /api/swagger
- Update SECURITY.md: Threat Model, Rate Limits, and Supported Versions tables

CHANGELOG.md

@@ -6,6 +6,54 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [1.7.0] - 2026-05-21
+
+### Added
+
+#### Swagger UI & OpenAPI 3.1 Documentation
+
+- **Swagger UI at `/api/swagger`** — Interactive API documentation served via `swagger-ui-express`; publicly accessible with a custom authentication banner (`public/swagger-auth-banner.js`) that explains the cookie-based + CSRF-token authentication flow for testing endpoints directly in the browser.
+- **OpenAPI 3.1 specification** — Central `server/openapi.yaml` file containing base metadata, security schemes (`CookieAuth`, `CsrfToken`), and reusable component schemas:
+  - `NormalizedDownload` — standardised download object returned by all PDCA clients
+  - `DashboardPayload` — SSE payload shape (`{ user, isAdmin, downloads, downloadClients }`)
+  - `ErrorResponse` — standard error envelope with redacted details
+  - `BlocklistSearchRequest` — payload for the admin blocklist-and-search operation
+  - `WebhookPayload` — Sonarr/Radarr webhook event structure
+  - `HistoryItem` — deduplicated history record with upgrade-availability flag
+  - `StatusResponse` — server metrics, polling timings, cache stats, and webhook metrics
+- **Hybrid documentation approach** — Per-endpoint details are documented directly in route handler files (`server/routes/*.js`) using JSDoc `@openapi` comments. `swagger-jsdoc` merges these comments with the central YAML at runtime, keeping documentation close to the code while maintaining shared schemas in one place.
+- **Comprehensive endpoint coverage** — All implemented endpoints are documented:
+  - Authentication: `POST /api/auth/login`, `GET /api/auth/me`, `GET /api/auth/csrf`, `POST /api/auth/logout`
+  - Dashboard: `GET /api/dashboard/stream` (SSE), `GET /api/dashboard/user-downloads` (deprecated), `GET /api/dashboard/cover-art`, `POST /api/dashboard/blocklist-search`
+  - Status: `GET /api/status`
+  - History: `GET /api/history/recent`
+  - Webhooks: `POST /api/webhook/sonarr`, `POST /api/webhook/radarr`
+  - Proxy routes: Sonarr, Radarr, SABnzbd, and Emby authenticated proxies
+  - Public health: `GET /health`, `GET /ready`
+- **Machine-usable extensions** — Every documented endpoint includes:
+  - `x-code-samples` with cURL, JavaScript fetch, and TypeScript examples
+  - `x-integration-notes` section in descriptions for AI agents and automated tooling
+  - Realistic request/response examples and full JSON Schema definitions
+- **Coverage validation test suite** — `tests/integration/swagger-coverage.test.js` (22 tests) validates that:
+  - The OpenAPI spec loads without YAML parse errors
+  - Every Express route appears in the merged spec
+  - All schema and response examples are valid JSON
+  - Required security schemes (`CookieAuth`, `CsrfToken`) are defined and referenced correctly
+  - The Swagger UI HTML endpoint (`GET /api/swagger`) returns `200`
+- **CI/CD validation job** — Added "Swagger Validation & Coverage" job in `.gitea/workflows/ci.yml` that runs on every push:
+  - Lints `server/openapi.yaml` with `@stoplight/spectral-cli`
+  - Runs `npm test -- tests/integration/swagger-coverage.test.js` to verify coverage
+
+### Changed
+
+- **Dependencies added** — `swagger-ui-express` (^5.0.1), `swagger-jsdoc` (^6.2.8), `yamljs` (^0.3.0), and `@stoplight/spectral-cli` (^6.16.0 dev dependency) for OpenAPI generation, UI serving, and spec linting.
+
+### Security
+
+- **Swagger UI public access** — The Swagger UI endpoint (`/api/swagger`) is publicly accessible by design for convenience. All documented API endpoints still enforce authentication (`emby_user` cookie) and CSRF protection (`X-CSRF-Token` header for mutations) as before. The authentication banner in the UI explicitly instructs users to log in via `POST /api/auth/login` first before testing protected endpoints.
+
+---
+
 ## [1.6.0] - 2026-05-21
 
 ### Added