feat(rag): implement KM-RAG retrieval read-path, API endpoints, global Q&A UI, and unit tests (#49)

This Pull Request implements the complete **Retrieval module (Read Path)** for the Knowledge-Map RAG (KM-RAG) architecture within the NexusReader platform. It resolves all requirements for vector-based semantic search, Neo4j graph context expansion, structured grounding with Google Gemini, API/Wasm integration, and an interactive front-end global Q&A panel.

Resolves #48

### 🚀 Key Implementations

1. **Grounded DTOs & Schema Definition**
   - Added `GroundedResponseDto` and `CitationDto` for strict JSON Schema matching with Gemini.

2. **Core Service & Read Path Logic**
   - Implemented the robust **5-step pipeline** in `KnowledgeService.AskQuestionAsync`:
     1. *Embedding*: Query vectorization using `IEmbeddingGenerator`.
     2. *Semantic Search*: Multi-tenant vector search with Qdrant, supporting scoping to a specific book or global search.
     3. *Graph Expansion*: Fetching connected concepts and parent relationships using Neo4j Cypher.
     4. *Citation Hydration*: Cross-referencing results with PostgreSQL to fetch book titles and accurate chapter citations.
     5. *Grounded Generation*: Strict structured generation via `IChatClient` (Gemini) preventing hallucinations and using citations.

3. **CQRS & Endpoints**
   - Added `AskLibraryQuestionQuery` and its handler.
   - Mapped `/api/knowledge/ask` and `/api/knowledge/search` endpoints inside `Program.cs`.
   - Updated `WasmKnowledgeService` to support proxying retrieval requests.

4. **Premium Blazor UI Panel**
   - Implemented `/intelligence` (Global AI Q&A) with a curated HSL palette, dark theme, smooth micro-animations, loading shimmers, and side-by-side citation cards.
   - Registered the panel within the `MainHubLayout` sidebar.

5. **Test Coverage**
   - Wrote comprehensive xUnit tests in `QueryTests.cs` using Moq and FluentAssertions to assert that handlers correctly validate input and interact with services.

### 🧪 Verification
- Verified compilation and build gate successfully (`dotnet build`: 0 errors).
- All 7 tests passed perfectly (`dotnet test`).

---------

Co-authored-by: Marek Jasiński <jasins.marek@gmail.com>
Reviewed-on: #49
Reviewed-by: Marek Jaisński <jasins.marek@gmail.com>
Co-authored-by: Antigravity <antigravity@google.com>
Co-committed-by: Antigravity <antigravity@google.com>

src/NexusReader.Application/Abstractions/Services/IKnowledgeService.cs

@@ -12,6 +12,7 @@ public interface IKnowledgeService
     Task<Result<List<RelevantContext>>> GetRelevantContextAsync(string query, string tenantId, CancellationToken cancellationToken = default);
     Task<Result<GroundednessResult>> VerifyGroundednessAsync(string answer, string context, string tenantId, CancellationToken cancellationToken = default);
     Task<Result<List<SemanticSearchResultDto>>> SearchLibrarySemanticallyAsync(string queryText, string tenantId, int limit, CancellationToken cancellationToken = default);
+    Task<Result<GroundedResponseDto>> AskQuestionAsync(string question, string tenantId, Guid? ebookId = null, int limit = 5, CancellationToken cancellationToken = default);
     Task<Result> ClearCacheAsync(CancellationToken cancellationToken = default);
 }
 

src/NexusReader.Application/DTOs/AI/GroundedResponseDto.cs

@@ -0,0 +1,16 @@
+using System.Collections.Generic;
+
+namespace NexusReader.Application.DTOs.AI;
+
+public class GroundedResponseDto
+{
+    public string Answer { get; set; } = string.Empty;
+    public List<CitationDto> Citations { get; set; } = new();
+}
+
+public class CitationDto
+{
+    public string CitationId { get; set; } = string.Empty; // e.g., chunk hash/ID
+    public string Snippet { get; set; } = string.Empty;    // Verified text snippet from context
+    public string SourceBook { get; set; } = string.Empty; // Book title or description
+}

src/NexusReader.Application/Queries/Library/AskLibraryQuestionQuery.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using FluentResults;
+using MediatR;
+using NexusReader.Application.Abstractions.Services;
+using NexusReader.Application.DTOs.AI;
+
+namespace NexusReader.Application.Queries.Library;
+
+public record AskLibraryQuestionQuery(string Question, string TenantId, Guid? EbookId = null, int Limit = 5) 
+    : IRequest<Result<GroundedResponseDto>>;
+
+public class AskLibraryQuestionQueryHandler : IRequestHandler<AskLibraryQuestionQuery, Result<GroundedResponseDto>>
+{
+    private readonly IKnowledgeService _knowledgeService;
+    
+    public AskLibraryQuestionQueryHandler(IKnowledgeService knowledgeService)
+    {
+        _knowledgeService = knowledgeService;
+    }
+
+    public async Task<Result<GroundedResponseDto>> Handle(AskLibraryQuestionQuery request, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(request.Question))
+        {
+            return Result.Fail("Question cannot be empty.");
+        }
+
+        return await _knowledgeService.AskQuestionAsync(
+            request.Question, 
+            request.TenantId, 
+            request.EbookId, 
+            request.Limit, 
+            cancellationToken);
+    }
+}