Add complete XML doc and Swagger annotations to all controller endpoints

Every public action now has <summary>, <param>, and <returns> XML docs
plus matching SwaggerOperation/SwaggerResponse attributes with typed response
descriptions. Class-level summaries added to CvController, JobSearchController,
and RagController. Explanatory inline comments removed from FileDownloadController
per project conventions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Apis/api/Controllers/CvMatcherController.cs

@@ -48,10 +48,18 @@ public sealed class CvMatcherController : ControllerBase
     }
 
     /// <summary>
-    /// Upload a CV PDF to the cv-matcher-api.
+    /// Proxies a CV PDF upload to the internal cv-matcher-api for indexing.
+    /// Validates the reCAPTCHA token and GDPR consent before forwarding.
+    /// Caches the uploaded file locally so it can be attached to the match result email.
     /// </summary>
-    /// <param name="request">The uploaded CV request.</param>
+    /// <param name="request">Multipart form containing the CV PDF, captcha token, and GDPR consent flag.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with the document ID and cache status from cv-matcher-api;
+    /// 400 Bad Request if the file is missing or captcha verification fails;
+    /// 499 if the client cancelled the request;
+    /// 502 Bad Gateway if the upstream cv-matcher-api call fails.
+    /// </returns>
     [HttpPost("upload")]
     [RequestSizeLimit(8 * 1024 * 1024)]
     [ProducesResponseType(StatusCodes.Status200OK)]
@@ -109,10 +117,18 @@ public sealed class CvMatcherController : ControllerBase
     }
 
     /// <summary>
-    /// Proxy a job matching request to the cv-matcher-api.
+    /// Proxies a CV-to-job match request to the internal cv-matcher-api.
+    /// Validates the reCAPTCHA token, then forwards the request and emails the scored result to the user.
+    /// When an email is provided, also creates a one-time job-search token and appends the search link to the email.
     /// </summary>
-    /// <param name="request">Job match request payload containing CV document id or job description/url.</param>
+    /// <param name="request">Match request containing the CV document ID, a job URL or inline description, and an optional recipient email.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with the <see cref="JobMatchResponse"/> score, strengths, and gaps;
+    /// 400 Bad Request if captcha verification fails;
+    /// 499 if the client cancelled the request;
+    /// 502 Bad Gateway if the upstream cv-matcher-api call fails.
+    /// </returns>
     [HttpPost("match-job")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
@@ -182,8 +198,20 @@ public sealed class CvMatcherController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Validates a one-time job-search token and kicks off the background job search.
+    /// Returns a self-contained HTML page intended to be opened directly in the browser via the link in the match email.
+    /// </summary>
+    /// <param name="t">The one-time UUID token from the job-search link query string.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with an HTML page indicating whether the search was started, the token was already used, expired, or invalid.
+    /// Always returns 200 — error states are communicated via the HTML page content, not the HTTP status code.
+    /// </returns>
     [HttpGet("job-search/start")]
-    [SwaggerOperation(Summary = "Start job search", Description = "Validates the one-time token and starts the background job search. Returns a simple HTML confirmation page.")]
+    [SwaggerOperation(Summary = "Start job search", Description = "Validates the one-time token and starts the background job search. Returns a self-contained HTML confirmation page.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "HTML page returned for all token states (started, already used, expired, invalid)")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
     public async Task<IActionResult> StartJobSearch([FromQuery] string t, CancellationToken ct)
     {
         try