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/cv-matcher-api/Controllers/JobSearchController.cs

@@ -3,9 +3,14 @@ using CvMatcher.Models.Requests;
 using CvMatcher.Models.Responses;
 using Microsoft.AspNetCore.Mvc;
 using Shared.Models.Responses;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace Api.Controllers;
 
+/// <summary>
+/// Internal endpoints for managing one-click job-search tokens and sessions.
+/// Routes are prefixed with <c>api/cv/job-search</c>. Protected by the internal API key middleware — not reachable from the public internet.
+/// </summary>
 [ApiController]
 [Route("api/cv/job-search")]
 public sealed class JobSearchController : ControllerBase
@@ -19,7 +24,26 @@ public sealed class JobSearchController : ControllerBase
         _logger = logger;
     }
 
+    /// <summary>
+    /// Creates a one-time job-search token linked to a CV document and email address.
+    /// Called by <c>api</c> immediately after a successful CV match when an email is provided.
+    /// The token is embedded in the job-search link sent to the user's email.
+    /// </summary>
+    /// <param name="request">The CV document ID and the recipient email address.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="CreateJobSearchTokenResponse"/> containing the generated token ID;
+    /// 400 Bad Request if <c>CvDocumentId</c> or <c>Email</c> is missing;
+    /// 500 Internal Server Error if token creation fails.
+    /// </returns>
     [HttpPost("token")]
+    [SwaggerOperation(Summary = "Create job search token", Description = "Creates a one-time token that lets the user start a background job search by clicking the link in their match email.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Token created successfully", typeof(CreateJobSearchTokenResponse))]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "CvDocumentId or Email missing", typeof(ErrorResponse))]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "Token creation failed", typeof(ErrorResponse))]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
     public async Task<ActionResult<CreateJobSearchTokenResponse>> CreateToken(
         [FromBody] CreateJobSearchTokenRequest request,
         CancellationToken ct)
@@ -39,7 +63,24 @@ public sealed class JobSearchController : ControllerBase
         }
     }
 
+    /// <summary>
+    /// Validates the one-time token, marks it as used, and enqueues a <c>JobSearchSession</c> with status <c>Pending</c>.
+    /// Called by <c>api</c> when the user clicks the job-search link in their match email.
+    /// The <c>cv-search-job</c> worker picks up the pending session and runs the search.
+    /// </summary>
+    /// <param name="tokenId">The UUID token extracted from the email link.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// 200 OK with a <see cref="StartJobSearchResponse"/> whose <c>Status</c> is one of
+    /// <c>Started</c>, <c>AlreadyUsed</c>, or <c>Expired</c>;
+    /// 500 Internal Server Error if the session cannot be created.
+    /// </returns>
     [HttpPost("token/{tokenId}/start")]
+    [SwaggerOperation(Summary = "Start job search", Description = "Validates the one-time token and creates a Pending job search session for the cv-search-job worker to process.")]
+    [SwaggerResponse(StatusCodes.Status200OK, "Search status returned (Started, AlreadyUsed, or Expired)", typeof(StartJobSearchResponse))]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "Session creation failed", typeof(ErrorResponse))]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
     public async Task<ActionResult<StartJobSearchResponse>> Start(string tokenId, CancellationToken ct)
     {
         try