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/cv-matcher-api/Services/CvMatcherService.cs

@@ -10,6 +10,9 @@ using Microsoft.Extensions.Options;
 
 namespace Api.Services;
 
+/// <summary>
+/// Orchestrates CV upload, RAG indexing, job text extraction, LLM scoring, and result caching.
+/// </summary>
 public sealed class CvMatcherService : ICvMatcherService
 {
     private readonly IRagApiClient _rag;
@@ -35,6 +38,7 @@ public sealed class CvMatcherService : ICvMatcherService
         _settings = options.Value;
     }
 
+    /// <inheritdoc />
     public async Task<CvUploadResponse> UploadCvAsync(IFormFile file, CancellationToken ct)
     {
         var response = await _rag.IndexCvPdfAsync(file, ct);
@@ -51,6 +55,7 @@ public sealed class CvMatcherService : ICvMatcherService
         };
     }
 
+    /// <inheritdoc />
     public async Task<FindJobsResponse> FindJobsAsync(FindJobsRequest request, CancellationToken ct)
     {
         var cv = await _rag.GetDocumentAsync(request.CvDocumentId, ct) ?? throw new InvalidOperationException("CV document not found.");
@@ -78,6 +83,7 @@ public sealed class CvMatcherService : ICvMatcherService
         return new FindJobsResponse { CvDocumentId = request.CvDocumentId, Jobs = jobs };
     }
 
+    /// <inheritdoc />
     public async Task<JobMatchResponse> MatchJobAsync(MatchJobRequest request, CancellationToken ct)
     {
         if (!request.GdprConsent) throw new InvalidOperationException("GDPR consent is required.");
@@ -104,6 +110,11 @@ public sealed class CvMatcherService : ICvMatcherService
         return await ScorePairAsync(cv, jobDocument, matchedChunks, request.Email, NormalizeLanguage(request.Language), ct);
     }
 
+    /// <summary>
+    /// Scores a (CV, job) pair with the LLM.
+    /// Returns a cached result immediately when the same (CV, job, language) triple has been scored before.
+    /// When no evidence chunks are available from the vector search, falls back to the raw job text.
+    /// </summary>
     private async Task<JobMatchResponse> ScorePairAsync(RagDocumentDetails cv, RagDocumentDetails job, IReadOnlyList<string> evidenceChunks, string? email, string language, CancellationToken ct)
     {
         var cached = await _repository.GetMatchAsync(cv.Id, job.Id, language, ct);
@@ -138,6 +149,10 @@ public sealed class CvMatcherService : ICvMatcherService
         return result;
     }
 
+    /// <summary>
+    /// Deserialises the LLM's JSON output into a <see cref="JobMatchResponse"/>.
+    /// Returns a safe fallback response instead of throwing when the JSON cannot be parsed.
+    /// </summary>
     private static JobMatchResponse ParseResult(string json)
     {
         try
@@ -158,21 +173,29 @@ public sealed class CvMatcherService : ICvMatcherService
         };
     }
 
+    /// <summary>
+    /// Builds a descriptive search query from the CV text for use in vector similarity search.
+    /// </summary>
     private static string BuildCvSearchProfile(string cvText)
     {
         var text = Limit(cvText, 10000);
         return $"Candidate profile, skills, technologies, seniority, industry experience, project experience: {text}";
     }
 
+    /// <summary>
+    /// Extracts a short job title from the first sentence-like fragment of the job text.
+    /// </summary>
     private static string ExtractJobTitle(string jobText)
     {
         var first = jobText.Split('.', '\n', '\r').Select(x => x.Trim()).FirstOrDefault(x => x.Length is > 8 and < 140);
         return first ?? "Job description";
     }
 
+    /// <summary>Returns the base language code, lower-cased, defaulting to <c>"en"</c>.</summary>
     private static string NormalizeLanguage(string? language) =>
         string.IsNullOrWhiteSpace(language) ? "en" : language.ToLowerInvariant().Split('-')[0].Trim();
 
+    /// <summary>Maps a language code to its full English name for use in the LLM system prompt.</summary>
     private static string LanguageName(string language) => language switch
     {
         "ro" => "Romanian",
@@ -180,5 +203,6 @@ public sealed class CvMatcherService : ICvMatcherService
         _ => "English"
     };
 
+    /// <summary>Truncates <paramref name="value"/> to at most <paramref name="max"/> characters.</summary>
     private static string Limit(string value, int max) => value.Length <= max ? value : value[..max];
 }