Clean up OpenAPI scripts

docs/ARCHITECTURE.md

@@ -6,17 +6,17 @@
 - `repositories/`: database helpers and migrations.
 - `common/`: reusable HTTP, auth, crypto, email and validation utilities.
 - `migrations/`: versioned SQL files.
-- `lab/`: local Streamlit frontend for visual endpoint testing.
+- `scripts/generate_openapi.py`: OpenAPI generator.
+- `scripts/lab/`: local Streamlit frontend for visual endpoint testing.
 - `docs/`: product, API, schema and milestone documentation.
 
 ## Drogon Usage
 Controllers use Drogon route macros and return JSON with
-`HttpResponse::newHttpJsonResponse`. Database access uses Drogon's MySQL client
-with parameterized SQL placeholders.
+`HttpResponse::newHttpJsonResponse`. Database access uses
+`drogon::orm::DbClient` with raw parameterized SQL placeholders.
 
-The codebase starts with raw SQL repositories because the schema is still
-evolving. Drogon ORM/codegen can be introduced later after the database model
-stabilizes.
+The codebase does not use Drogon generated models or `Mapper<T>`. Raw SQL stays
+in repository/database helpers because the schema is still evolving.
 
 ## Local Email
 OTP emails are sent to MailHog over SMTP. MailHog keeps messages local and
@@ -29,16 +29,17 @@ available through OpenSSL, which is already a Drogon dependency in this project.
 Legacy `sha256$` password hashes are rejected instead of silently accepted.
 
 ## OpenAPI Generation
-`generate_openapi.py` scans Drogon `ADD_METHOD_TO` route macros in
-`controllers/*.h` and generates `build/openapi/visione.openapi.json`.
+`scripts/generate_openapi.py` scans Drogon `ADD_METHOD_TO` route macros and the
+adjacent `openapi:` metadata blocks in `controllers/*.h`, then 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.
+generates paths, methods, path parameters, summaries, descriptions, auth hints
+and common JSON or multipart request bodies. Generation fails if a route lacks
+metadata.
 
 ## Visione Lab
-`lab/` is a Streamlit dev frontend for visual endpoint testing. It is
+`scripts/lab/` is a Streamlit dev frontend for visual endpoint testing. It is
 intentionally separate from the real product frontend and should stay small:
-forms, uploads and response rendering only. Run it with uv from `lab/`.
+forms, uploads and response rendering only. Run it with uv from `scripts/lab/`.