Simplify OpenAPI generation

docs/ARCHITECTURE.md

@@ -6,9 +6,8 @@
 - `repositories/`: database helpers and migrations.
 - `common/`: reusable HTTP, auth, crypto, email and validation utilities.
 - `migrations/`: versioned SQL files.
-- `scripts/swagger-drogon/`: OpenAPI generator package.
-- `scripts/generate_openapi.py`: compatibility wrapper for the generator.
-- `docs/openapi/`: app-specific OpenAPI schema registry.
+- `scripts/generate_openapi.py`: minimal OpenAPI route extractor.
+- `docs/openapi/`: manual OpenAPI contract documents.
 - `scripts/lab/`: local Streamlit frontend for visual endpoint testing.
 - `docs/`: product, API, schema and milestone documentation.
 
@@ -31,17 +30,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
-`scripts/swagger-drogon/` scans Drogon `ADD_METHOD_TO` route macros and the
-adjacent `openapi:` metadata blocks in `controllers/*.h`. It also inspects
-controller/service `.cc` files for simple query, JSON field and response field
-patterns, then merges the app-specific registry in `docs/openapi/visione.yaml`.
-The CMake `openapi` target writes `build/openapi/visione.openapi.json`.
+`scripts/generate_openapi.py` scans Drogon `ADD_METHOD_TO` route macros in
+`controllers/*.h` and extracts only paths, HTTP methods, operation ids, tags and
+path parameters. It merges those route skeletons with
+`docs/openapi/visione.openapi.yaml`, which owns summaries, request bodies,
+responses, schemas and examples. The manual file uses JSON-compatible YAML so
+the CMake `openapi` target can run without extra Python packages and writes
+`build/openapi/visione.openapi.json`.
 
-This is a hybrid generator: C++ is the source of truth for routes and metadata,
-while YAML provides schemas that cannot be safely inferred from dynamic
-`Json::Value` payloads and raw SQL result rows. Generation fails if a route lacks
-metadata, has unresolved schema refs, emits `/photos`, or leaves operation
-request/response schemas as generic objects.
+If the manual YAML contains an operation that no longer exists in the Drogon
+route list, generation fails unless that operation is explicitly marked
+`x-manual-only: true`.
 
 ## Visione Lab
 `scripts/lab/` is a Streamlit dev frontend for visual endpoint testing. It is