Add XML doc to all service interfaces and implementations (#26)

- Update CLAUDE.md: replace incorrect 'no XML doc on internal code' rule
  with the correct convention (XML doc on all public methods and
  non-trivial private/protected helpers)
- Restore /// <summary> on FileDownloadController private helpers
  (HandleRangeRequest, StreamRangeAsync)
- Add full XML doc to all service contracts:
  ICaptchaVerifier, IEmailSender, ICvMatcherService, IJobTextExtractor,
  IJobTokenService, IDocumentClassifier, IRagService, ITextChunker,
  ITextExtractor, IEmailTemplateService, ITemplateService
- Add /// <summary> and /// <inheritdoc /> to all concrete service classes
  and their methods: RecaptchaVerifier, EmailApiEmailSender,
  SmtpEmailDispatcher, CvMatcherService, JobTextExtractor, JobTokenService,
  RagService, DocumentClassifier, TextChunker, TextExtractor,
  HtmlJobSearcher, CvSearchEmailSender, CvSearchJobTask,
  EmailTemplateService, DbTemplateService

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

Apis/api/Services/Contracts/ICaptchaVerifier.cs

@@ -1,9 +1,21 @@
-using Api.Services.Contracts.Models;
+using Api.Services.Contracts.Models;
 
 namespace Api.Services.Contracts
 {
+    /// <summary>
+    /// Verifies a reCAPTCHA token against the Google verification API.
+    /// </summary>
     public interface ICaptchaVerifier
     {
+        /// <summary>
+        /// Sends the token to the Google reCAPTCHA verification endpoint and
+        /// returns a verdict indicating success, score, and any failure reason.
+        /// </summary>
+        /// <param name="token">The reCAPTCHA token provided by the client.</param>
+        /// <param name="userIp">Optional remote IP address passed to Google for additional risk analysis.</param>
+        /// <param name="expectedAction">Optional action name to validate against the token's embedded action (v3 only).</param>
+        /// <param name="ct">Cancellation token.</param>
+        /// <returns>A <see cref="CaptchaVerdictModel"/> with the verification outcome.</returns>
         Task<CaptchaVerdictModel> VerifyAsync(string token, string? userIp, string? expectedAction, CancellationToken ct);
     }
 }

Apis/api/Services/Contracts/IEmailSender.cs

@@ -1,15 +1,65 @@
-using CvMatcher.Models.Responses;
+using CvMatcher.Models.Responses;
 using Models.Requests;
 
 namespace Api.Services.Contracts
 {
+    /// <summary>
+    /// Abstraction for sending transactional emails from the public API.
+    /// </summary>
     public interface IEmailSender
     {
+        /// <summary>
+        /// Sends a contact-form message to the configured operator address.
+        /// </summary>
+        /// <param name="req">Contact request containing name, email, subject, and message.</param>
+        /// <param name="ct">Cancellation token.</param>
         Task SendContactAsync(ContactRequest req, CancellationToken ct);
+
+        /// <summary>
+        /// Notifies the configured operator address that a new email subscription was received.
+        /// </summary>
+        /// <param name="req">Subscription request containing the subscriber's email address.</param>
+        /// <param name="ct">Cancellation token.</param>
         Task SendSubscribeAsync(SubscribeRequest req, CancellationToken ct);
+
+        /// <summary>
+        /// Sends a background notification when a file download is initiated.
+        /// Does nothing when no notification address is configured.
+        /// </summary>
+        /// <param name="fileName">Name of the downloaded file.</param>
+        /// <param name="userIp">Remote IP address of the downloader, or <c>null</c> if unavailable.</param>
+        /// <param name="ct">Cancellation token.</param>
         Task SendFileDownloadNotificationAsync(string fileName, string? userIp, CancellationToken ct);
+
+        /// <summary>
+        /// Sends a CV match results email to the user and the operator copy address.
+        /// </summary>
+        /// <param name="explicitTo">Primary recipient email address, or <c>null</c> to send only the operator copy.</param>
+        /// <param name="subject">Email subject line.</param>
+        /// <param name="body">Pre-built HTML body fragment.</param>
+        /// <param name="attachmentPath">Full path to a CV PDF to attach, or <c>null</c> for no attachment.</param>
+        /// <param name="ct">Cancellation token.</param>
         Task SendMatchAsync(string? explicitTo, string subject, string body, string? attachmentPath, CancellationToken ct);
+
+        /// <summary>
+        /// Builds the localised subject line for a CV match email.
+        /// </summary>
+        /// <param name="score">Match score percentage (0–100).</param>
+        /// <param name="jobLabel">Human-readable job title or label.</param>
+        /// <param name="language">Two-letter language code (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
+        /// <returns>Rendered subject string.</returns>
         string BuildMatchEmailSubject(int score, string? jobLabel, string language);
+
+        /// <summary>
+        /// Builds the full HTML body for a CV match email, including an optional job-search footer link.
+        /// </summary>
+        /// <param name="cvDocumentId">Identifier of the indexed CV document.</param>
+        /// <param name="result">Structured match response from the CV matcher engine.</param>
+        /// <param name="jobLabel">Human-readable job title or label.</param>
+        /// <param name="language">Two-letter language code.</param>
+        /// <param name="jobSearchLink">Optional one-click job-search URL to append as a footer CTA.</param>
+        /// <param name="expiryDays">Number of days until the job-search link expires (shown in the footer copy).</param>
+        /// <returns>Rendered HTML body string.</returns>
         string BuildMatchEmailBody(string cvDocumentId, JobMatchResponse result, string? jobLabel, string language, string? jobSearchLink = null, int expiryDays = 7);
     }
 }

Apis/api/Services/EmailApiEmailSender.cs

@@ -9,6 +9,9 @@ using Models.Settings;
 
 namespace Api.Services;
 
+/// <summary>
+/// Implements <see cref="IEmailSender"/> by delegating all email dispatch to the internal email-api service via Refit.
+/// </summary>
 public sealed class EmailApiEmailSender : IEmailSender
 {
     private readonly IEmailApiClient _emailApi;
@@ -34,6 +37,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         _log = log;
     }
 
+    /// <inheritdoc />
     public async Task SendContactAsync(ContactRequest req, CancellationToken ct)
     {
         if (string.IsNullOrWhiteSpace(_contact.ToEmail))
@@ -76,6 +80,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         _log.LogInformation("Contact email sent successfully from {SenderEmail}", req.Email);
     }
 
+    /// <inheritdoc />
     public async Task SendSubscribeAsync(SubscribeRequest req, CancellationToken ct)
     {
         if (string.IsNullOrWhiteSpace(_subscribe.ToEmail))
@@ -108,6 +113,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         _log.LogInformation("Subscription email sent successfully for {Email}", req.Email);
     }
 
+    /// <inheritdoc />
     public async Task SendFileDownloadNotificationAsync(string fileName, string? userIp, CancellationToken ct)
     {
         if (string.IsNullOrWhiteSpace(_fileStorage.ToEmail))
@@ -146,6 +152,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         _log.LogInformation("File download notification sent successfully for {FileName}", fileName);
     }
 
+    /// <inheritdoc />
     public async Task SendMatchAsync(string? explicitTo, string subject, string body, string? attachmentPath, CancellationToken ct)
     {
         var operatorCopy = _emailTemplates.GetOperatorCopy("email.match.subject", "en");
@@ -184,6 +191,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         }
     }
 
+    /// <inheritdoc />
     public string BuildMatchEmailBody(string cvDocumentId, JobMatchResponse result, string? jobLabel, string language, string? jobSearchLink = null, int expiryDays = 7)
     {
         var strengths = result.Strengths?.Count > 0
@@ -221,6 +229,7 @@ public sealed class EmailApiEmailSender : IEmailSender
         return body;
     }
 
+    /// <inheritdoc />
     public string BuildMatchEmailSubject(int score, string? jobLabel, string language) =>
         _emailTemplates.Render("email.match.subject", language,
             ("score", score.ToString()),

Apis/api/Services/RecaptchaVerifier.cs

@@ -5,6 +5,9 @@ using Models.Settings;
 
 namespace Api.Services
 {
+    /// <summary>
+    /// Verifies reCAPTCHA v2/v3 tokens by calling the Google site-verify API.
+    /// </summary>
     public sealed class RecaptchaVerifier : ICaptchaVerifier
     {
         private readonly HttpClient _http;
@@ -18,6 +21,7 @@ namespace Api.Services
             _log = log;
         }
 
+        /// <inheritdoc />
         public async Task<CaptchaVerdictModel> VerifyAsync(string token, string? userIp, string? expectedAction, CancellationToken ct)
         {
             _log.LogDebug("Verifying captcha token for IP {Ip}", userIp ?? "unknown");