docs(adr): convert all ADRs to MADR 2.1.2 format

Rewrites all 7 backend ADRs from a custom structure to the MADR 2.1.2
template required by the VS Code ADR Manager extension: bullet metadata
(Status/Date), standardised section headings, "Chosen option: X, because Y"
wording, and explicit Pros/Cons blocks per option.

docs/decisions/0003-rest-api-with-swagger.md

@@ -1,23 +1,50 @@
-# ADR 0003: REST API with Swagger Documentation
+# Document the REST API with OpenAPI/Swagger
 
-**Date:** 2026-04-26
-**Status:** Accepted
+* Status: accepted
+* Date: 2026-04-26
 
-## Context
+## Context and Problem Statement
 
-The API must be understandable and testable without reading source code. Two documentation approaches were considered:
-- **OpenAPI/Swagger** — industry standard, generates interactive UI, supports code generation.
-- **Postman collection** — already present (`tests/adastra-api-tests.postman_collection.json`), good for integration testing but not a substitute for living documentation.
+The API must be understandable and testable without reading source code. How should the API be documented?
 
-## Decision
+## Considered Options
 
-Use `swagger-jsdoc` + `swagger-ui-express` to generate and serve an interactive OpenAPI 3.0 documentation at a dedicated route. Annotations are written as JSDoc comments directly in route/controller files.
+* OpenAPI/Swagger (`swagger-jsdoc` + `swagger-ui-express`)
+* Postman collection only
+* No documentation
 
-Postman collections are kept for integration/regression testing (run via `npm run test:postman` with Newman), complementing rather than replacing Swagger.
+## Decision Outcome
 
-## Consequences
+Chosen option: "OpenAPI/Swagger", because it generates living, interactive documentation directly from the source code, eliminating the risk of documentation drift.
 
-- **Positive:** Living documentation — always in sync with the code.
-- **Positive:** Interactive UI allows manual endpoint testing without a separate tool.
-- **Positive:** OpenAPI spec can be used to generate client types if needed.
-- **Negative:** JSDoc annotations add verbosity to route files. Annotations must be kept up to date manually.
+`swagger-jsdoc` + `swagger-ui-express` generate and serve an interactive OpenAPI 3.0 UI at a dedicated route. Annotations are written as JSDoc comments directly in route/controller files. The existing Postman collection (`tests/adastra-api-tests.postman_collection.json`) is kept for integration and regression testing via Newman (`npm run test:postman`), complementing rather than replacing Swagger.
+
+### Positive Consequences
+
+* Living documentation — always in sync with the code.
+* Interactive UI allows manual endpoint testing without a separate tool.
+* OpenAPI spec can be used to generate client types if needed.
+
+### Negative Consequences
+
+* JSDoc annotations add verbosity to route files.
+* Annotations must be kept up to date manually — stale annotations are possible if discipline slips.
+
+## Pros and Cons of the Options
+
+### OpenAPI/Swagger
+
+* Good, because interactive UI — testable in the browser without Postman.
+* Good, because spec is co-located with the code it describes.
+* Bad, because requires discipline to keep annotations accurate.
+
+### Postman collection only
+
+* Good, because already present; useful for regression testing.
+* Bad, because not suitable as primary documentation — requires Postman to view.
+* Bad, because collection and code can diverge silently.
+
+### No documentation
+
+* Good, because zero maintenance overhead.
+* Bad, because API is opaque without reading the source.