Add OpenAPI generator

docs/API_SPEC.md

@@ -5,6 +5,8 @@ Base path: `/api/v1`.
 ## Technical
 - `GET /health`: process health.
 - `GET /ready`: MySQL readiness.
+- `GET /openapi.json`: generated OpenAPI 3.0 JSON.
+- `GET /docs`: Swagger UI page backed by the generated spec.
 
 ## Auth
 - `POST /auth/register`: create a citizen account.

docs/ARCHITECTURE.md

@@ -6,6 +6,7 @@
 - `repositories/`: database helpers and migrations.
 - `common/`: reusable HTTP, auth, crypto, email and validation utilities.
 - `migrations/`: versioned SQL files.
+- `tools/`: local developer tools such as OpenAPI generation.
 - `docs/`: product, API, schema and milestone documentation.
 
 ## Drogon Usage
@@ -21,3 +22,18 @@ stabilizes.
 OTP emails are sent to MailHog over SMTP. MailHog keeps messages local and
 inspectable through its web UI.
 
+## Password Hashing
+User passwords use PBKDF2-HMAC-SHA256 with per-password random salts and 210000
+iterations. This is intentionally slower than a plain SHA-256 digest and is
+available through OpenSSL, which is already a Drogon dependency in this project.
+Legacy `sha256$` password hashes are rejected instead of silently accepted.
+
+## OpenAPI Generation
+`tools/drogon-openapi-gen/generate.py` scans Drogon `ADD_METHOD_TO` route macros
+in `controllers/*.h` and generates `build/openapi/visione.openapi.json`.
+
+This is a contract-last generator: the source of truth is the C++ controller
+route list, not a manually maintained static Swagger document. The current tool
+generates paths, methods, path parameters, bearer auth hints and common JSON or
+multipart request bodies. Deeper request/response schemas can be added later by
+teaching the generator project-specific conventions or comments.