auth(2fa): add one-time recovery codes with regenerate/status APIs

docs/api-reference.md

@@ -93,11 +93,13 @@ For `/health/ready` failure:
 {
   "email": "user@example.com",
   "password": "strongpassword",
-  "otp_code": "123456"
+  "otp_code": "123456",
+  "recovery_code": "ABCDE-12345"
 }
 ```
 
-`otp_code` is optional and used only when 2FA is enabled.
+`otp_code` is optional and used when 2FA is enabled.
+`recovery_code` is optional one-time fallback when 2FA is enabled.
 
 ### TokenResponse
 
@@ -577,6 +579,36 @@ Body:
 
 Response: `200` + `MessageResponse`
 
+### POST `/api/v1/auth/2fa/recovery-codes/regenerate`
+
+Auth required.
+Body:
+
+```json
+{ "code": "123456" }
+```
+
+Response:
+
+```json
+{
+  "codes": ["ABCDE-12345", "FGHIJ-67890"]
+}
+```
+
+Codes are one-time and shown only at generation time.
+
+### GET `/api/v1/auth/2fa/recovery-codes/status`
+
+Auth required.
+Response:
+
+```json
+{
+  "remaining_codes": 8
+}
+```
+
 ## 6. Users endpoints
 
 ### GET `/api/v1/users/me`