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/Contracts/ICvMatcherService.cs

@@ -3,9 +3,34 @@ using CvMatcher.Models.Responses;
 
 namespace Api.Services.Contracts;
 
+/// <summary>
+/// Orchestrates CV indexing, job matching, and job discovery operations.
+/// </summary>
 public interface ICvMatcherService
 {
+    /// <summary>
+    /// Indexes a CV PDF into the RAG system and returns document metadata.
+    /// Returns cached metadata without re-indexing when the same text hash already exists.
+    /// </summary>
+    /// <param name="file">Uploaded CV PDF file.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Upload response with document ID, hash, and indexing statistics.</returns>
     Task<CvUploadResponse> UploadCvAsync(IFormFile file, CancellationToken ct);
+
+    /// <summary>
+    /// Scores a CV against a specific job posting URL or pasted description using the LLM.
+    /// Caches the result so repeat requests for the same (CV, job, language) triple are served instantly.
+    /// </summary>
+    /// <param name="request">Match request containing CV document ID, job URL or description, and language preference.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Structured match response with score, summary, strengths, gaps, and recommendations.</returns>
     Task<JobMatchResponse> MatchJobAsync(MatchJobRequest request, CancellationToken ct);
+
+    /// <summary>
+    /// Searches the RAG index for job documents most similar to the given CV and scores the top candidates.
+    /// </summary>
+    /// <param name="request">Request containing the CV document ID and optional result count limit.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Response with the CV document ID and a list of ranked match results.</returns>
     Task<FindJobsResponse> FindJobsAsync(FindJobsRequest request, CancellationToken ct);
 }

Apis/cv-matcher-api/Services/Contracts/IJobTextExtractor.cs

@@ -1,6 +1,17 @@
 namespace Api.Services.Contracts;
 
+/// <summary>
+/// Extracts plain text from a job posting, either from a pasted description or by fetching and parsing a URL.
+/// </summary>
 public interface IJobTextExtractor
 {
+    /// <summary>
+    /// Returns normalised plain text for the job posting.
+    /// Prefers <paramref name="jobDescription"/> when provided; otherwise fetches and strips HTML from <paramref name="jobUrl"/>.
+    /// </summary>
+    /// <param name="jobUrl">URL of the job posting page, used when no description is pasted.</param>
+    /// <param name="jobDescription">Pasted job description text; takes priority over URL fetching.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Normalised plain text, truncated to the configured maximum character limit.</returns>
     Task<string> ExtractAsync(string? jobUrl, string? jobDescription, CancellationToken ct);
 }

Apis/cv-matcher-api/Services/Contracts/IJobTokenService.cs

@@ -1,7 +1,29 @@
 namespace Api.Services.Contracts;
 
+/// <summary>
+/// Manages one-time job search tokens and the sessions they trigger.
+/// </summary>
 public interface IJobTokenService
 {
+    /// <summary>
+    /// Creates a new single-use job search token linked to the given CV document and user.
+    /// The token expires after the number of days configured in <c>JobSearch:TokenExpiryDays</c>.
+    /// </summary>
+    /// <param name="cvDocumentId">Identifier of the indexed CV document.</param>
+    /// <param name="email">Email address of the user who will receive the results.</param>
+    /// <param name="language">Preferred language for result emails (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The generated token ID, to be embedded in the one-click job search link.</returns>
     Task<string> CreateTokenAsync(string cvDocumentId, string email, string language, CancellationToken ct);
+
+    /// <summary>
+    /// Validates the token and, if valid, marks it as used and creates a <c>Pending</c> job search session.
+    /// </summary>
+    /// <param name="tokenId">The token ID from the one-click link.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// One of the <c>StartJobSearchStatus</c> string constants:
+    /// <c>Started</c>, <c>AlreadyUsed</c>, <c>Expired</c>, or <c>NotFound</c>.
+    /// </returns>
     Task<string> TriggerStartAsync(string tokenId, CancellationToken ct);
 }