feat: AI-native rebuild + production polish (closes #8 #9 #13 #15 #30 #31) (#51)

* chore(repo): AGENTS.md + citations contract + CORS/OpenAPI + PDF rasterizer seam (Refs #41)

* feat(ocr): capture source-span geometry + scanned-PDF OCR + BdxReviewPayload (Refs #41, #13)

* feat(extraction): optional Ollama LLM field extractor with deterministic-first merge (Refs #41, #15)

* feat(ingest): inbound-source + parser-adapter seams, Docling flag, file-based email source (Refs #41, #8, #9)

* feat(api): review-payload, page images, settings, schema-mappings, inbound-sources + agent tool endpoints (Refs #41)

* feat(extraction): wire real Ollama IChatClient field proposals behind the flag (Refs #41, #15)

* chore(web): scaffold Next.js 16 + AI SDK 6 + ollama-ai-provider-v2 + zod frontend (Refs #41)

* feat(web): institutional-calm design system, app shell, and typed API client (Refs #41)

* feat(web): AG-UI assistant route over local Ollama with useChat panel (Refs #41, #15)

* feat(web): workspace, source-cited review split-view, export, and settings (Refs #41, #13, #30, #31)

* refactor(web): cut over Reva.Web to API-only host; repoint e2e to API smoke (Refs #41, #31)

* feat(web): first-run onboarding tour, a11y polish, and Playwright e2e specs (Refs #41, #30, #31)

* feat(web): assistant dock minimize/expand, image + document attachments, new conversation; raise agent num_ctx so vision attachments are not truncated (Closes #43)

* design(web): verdict-first review experience — reconciliation with money deltas up top, grouped fields, plain language, line-items table, review actions (Closes #49, #45)

* feat(web): per-sender schema-mapping management page (Closes #47)

* feat(web): export template editor (create/edit/duplicate/delete) + format-aware download (Closes #46)

* feat(review): real document preview with per-line citation overlay

Render ingested raster images and rendered PDF pages as a real document
viewer in the review split-view: zoom, fit-to-width, page navigation,
loading state, and citation bounding-box overlays that scale with zoom.
Workspace queue rows show a page thumbnail for image and PDF documents,
falling back to the document icon for digital files.

Wire the image OCR path to emit a page (stored image plus real pixel
dimensions) and real-dimension source spans so image documents render
with overlays. Replace the reflection-based OpenCV region reader with the
typed RotatedRect API so per-line bounding boxes are captured instead of
a full-page fallback (also fixes citations on the scanned-PDF path). Seed
a scanned-bordereau image sample so the preview and overlays are
demonstrable end to end.

Closes #50

* feat(settings): reconciliation tolerance, LLM-assist toggle, data management, default template

Add two persisted app settings — money reconciliation tolerance and a local
LLM-assist toggle — and surface them on the Settings page alongside a default
export-template selector and demo data management (reseed and clear).

The reconciliation engine reads the configured tolerance instead of a fixed
threshold, and ingestion only invokes the LLM extractor when assist is enabled
so extraction stays fully deterministic by default. New POST /api/data/reseed
and /api/data/clear endpoints back the data-management actions, and the export
view pre-selects the configured default template.

Closes #44

* test(web): green Playwright e2e suite + axe accessibility pass

Run the end-to-end suite against the live stack and bring it to green:
- a shared fixture suppresses the first-run tour so specs start unobstructed
- a new assistant spec covers opening the dock and sending a message
- the onboarding spec drives the tour to completion via the persisted flag,
  tolerating route changes and auto-skipped steps
- correct the review field-row selector after the verdict-first redesign

Accessibility: zero serious or critical axe violations on /, /review, /export,
and /settings. Wrap queue rows in listitem (aria-required-children), mark the
collapsed assistant dock inert so its controls leave the focus and a11y tree,
label the upload file input, underline in-text links, and raise the
subtle-foreground and success token contrast to meet WCAG AA.

Closes #48

Author: xt0n1-t3ch

.github/workflows/ci.yml

@@ -34,7 +34,4 @@ jobs:
           dotnet-version: 10.0.x
       - run: dotnet build Reva.slnx
       - run: dotnet build tests/Reva.E2E/Reva.E2E.csproj
-      - shell: pwsh
-        name: Install Playwright browser
-        run: tests/Reva.E2E/bin/Debug/net10.0/playwright.ps1 install chromium
       - run: dotnet test tests/Reva.E2E/Reva.E2E.csproj --no-build

.gitignore

@@ -54,3 +54,4 @@ Thumbs.db
 .idea/
 .vscode/*
 !.vscode/extensions.json
+.proof/

AGENTS.md

@@ -0,0 +1,24 @@
+# Reva agent guide
+
+## Commands
+- Restore/build: `dotnet build Reva.slnx -warnaserror`
+- Tests: `dotnet test`
+- Format before EF migration commits: `dotnet format`
+- Run app without browser: `dotnet run --project src/Reva.Web/Reva.Web.csproj -- --no-open`
+
+## Layout
+- Core contracts and domain types: `src/Reva.Core`
+- Backend services, parsing, extraction, OCR, persistence: `src/Reva.Infrastructure`
+- Blazor host and HTTP API endpoints: `src/Reva.Web`
+- Unit/integration tests: `tests/Reva.Unit`, `tests/Reva.Integration`
+- Contract schemas: `contracts`
+
+## Boundaries
+- Do not edit `src/Reva.Web/Components/**`, `web/**`, `tests/Reva.E2E/**`, CI workflows, or release automation unless Tony explicitly scopes it.
+- Keep the keyless/offline default path working. External AI and Docling paths stay disabled unless config enables them.
+- Secrets come from environment or local config only and are never committed.
+
+## API contracts
+- Review payloads follow `contracts/bdx-review-payload.schema.json`.
+- Bounding boxes are normalized to `0..1` against the final rendered page size.
+- Provenance is always present; citations may be empty only when geometry is unavailable.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

contracts/bdx-review-payload.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://reva.local/contracts/bdx-review-payload.schema.json",
+  "title": "BdxReviewPayload",
+  "type": "object",
+  "required": ["document", "sourceSpans", "fields", "lineItems", "reconciliation"],
+  "additionalProperties": false,
+  "$defs": {
+    "bbox": { "type": "object", "required": ["x", "y", "width", "height"], "additionalProperties": false, "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 } } },
+    "point": { "type": "object", "required": ["x", "y"], "additionalProperties": false, "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } } },
+    "citation": { "type": "object", "required": ["sourceSpanId", "page", "bbox", "role"], "additionalProperties": false, "properties": { "sourceSpanId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1 }, "bbox": { "$ref": "#/$defs/bbox" }, "quote": { "type": ["string", "null"] }, "role": { "enum": ["value", "label", "header", "row", "control-total", "supporting"] } } },
+    "provenance": { "type": "object", "required": ["method", "stepId", "citations"], "additionalProperties": false, "properties": { "method": { "enum": ["digital_parse", "csv_parse", "excel_parse", "paddle_ocr", "schema_mapping", "llm_proposal", "merge", "manual"] }, "stepId": { "type": "string", "minLength": 1 }, "model": { "type": ["string", "null"] }, "promptVersion": { "type": ["string", "null"] }, "citations": { "type": "array", "items": { "$ref": "#/$defs/citation" } } } },
+    "fieldValue": { "type": "object", "required": ["key", "label", "value", "status", "confidence", "provenance"], "additionalProperties": false, "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "rawText": { "type": ["string", "null"] }, "status": { "enum": ["detected", "expected", "missing", "conflict", "low_confidence", "user_confirmed"] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "provenance": { "$ref": "#/$defs/provenance" } } }
+  },
+  "properties": {
+    "document": { "type": "object", "required": ["id", "filename", "pages"], "additionalProperties": false, "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "pages": { "type": "array", "items": { "type": "object", "required": ["page", "imageUrl", "width", "height", "rotation"], "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "imageUrl": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "rotation": { "enum": [0, 90, 180, 270] } } } } } },
+    "sourceSpans": { "type": "array", "items": { "type": "object", "required": ["id", "documentId", "page", "pageWidth", "pageHeight", "rotation", "bbox", "text"], "additionalProperties": false, "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "pageWidth": { "type": "number" }, "pageHeight": { "type": "number" }, "rotation": { "enum": [0, 90, 180, 270] }, "bbox": { "$ref": "#/$defs/bbox" }, "polygon": { "type": "array", "items": { "$ref": "#/$defs/point" } }, "text": { "type": "string" }, "ocrConfidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "blockId": { "type": ["string", "null"] }, "tableId": { "type": ["string", "null"] }, "rowIndex": { "type": ["integer", "null"], "minimum": 0 }, "columnIndex": { "type": ["integer", "null"], "minimum": 0 } } } },
+    "fields": { "type": "array", "items": { "$ref": "#/$defs/fieldValue" } },
+    "lineItems": { "type": "array", "items": { "type": "object", "required": ["id", "rowNumber", "fields", "rowCitationIds"], "additionalProperties": false, "properties": { "id": { "type": "string" }, "rowNumber": { "type": "integer", "minimum": 1 }, "fields": { "type": "array", "items": { "$ref": "#/$defs/fieldValue" } }, "rowCitationIds": { "type": "array", "items": { "type": "string" } } } } },
+    "reconciliation": { "type": "array", "items": { "type": "object", "required": ["id", "name", "expected", "detected", "delta", "tolerance", "status", "explanation", "citations"], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "expected": { "$ref": "#/$defs/fieldValue" }, "detected": { "$ref": "#/$defs/fieldValue" }, "delta": { "type": "number" }, "tolerance": { "type": "number" }, "status": { "enum": ["pass", "fail", "warning", "not_applicable"] }, "explanation": { "type": "string" }, "citations": { "type": "array", "items": { "$ref": "#/$defs/citation" } } } } }
+  }
+}

docs/index.md

@@ -2,8 +2,7 @@
 
 | Doc | What it covers |
 |:---|:---|
-| [architecture.md](architecture.md) | Backend-first architecture, contracts, data flow, and adapter boundaries. |
-| [ai-pipeline.md](ai-pipeline.md) | Native .NET parser router, offline PaddleOCR, the reconciliation engine, and the optional LLM seam. |
+| [architecture.md](architecture.md) | API-only .NET host, Next.js `web/` UI, contracts, data flow, and adapter boundaries. |
+| [ai-pipeline.md](ai-pipeline.md) | Native .NET parser router, offline PaddleOCR, local Ollama seam, and reconciliation. |
 | [packaging.md](packaging.md) | Windows executable packaging and smoke-test flow. |
-| [demo-script.md](demo-script.md) | Five-minute product walkthrough. |
 | [research/reinsurance-landscape.md](research/reinsurance-landscape.md) | Domain + market research grounding the product: document types, fields, must-have features, competitor patterns, standards. |

src/Reva.Core/Contracts/BdxReviewPayload.cs

@@ -0,0 +1,68 @@
+namespace Reva.Core.Contracts;
+
+public sealed record SourceBox(double X, double Y, double Width, double Height);
+
+public sealed record SourcePoint(double X, double Y);
+
+public sealed record SourceSpan(
+    string Id,
+    Guid DocumentId,
+    int Page,
+    double PageWidth,
+    double PageHeight,
+    int Rotation,
+    SourceBox Bbox,
+    IReadOnlyList<SourcePoint>? Polygon,
+    string Text,
+    double? OcrConfidence,
+    string? BlockId,
+    string? TableId,
+    int? RowIndex,
+    int? ColumnIndex);
+
+public sealed record Citation(
+    string SourceSpanId,
+    int Page,
+    SourceBox Bbox,
+    string? Quote,
+    string Role);
+
+public sealed record FieldProvenance(
+    string Method,
+    string StepId,
+    string? Model,
+    string? PromptVersion,
+    IReadOnlyList<Citation> Citations);
+
+public sealed record FieldValue(
+    string Key,
+    string Label,
+    string Value,
+    string? RawText,
+    string Status,
+    double Confidence,
+    FieldProvenance Provenance);
+
+public sealed record ReconciliationCheck(
+    string Id,
+    string Name,
+    FieldValue Expected,
+    FieldValue Detected,
+    double Delta,
+    double Tolerance,
+    string Status,
+    string Explanation,
+    IReadOnlyList<Citation> Citations);
+
+public sealed record BdxPage(int Page, string ImageUrl, double Width, double Height, int Rotation);
+
+public sealed record BdxDocument(Guid Id, string Filename, IReadOnlyList<BdxPage> Pages);
+
+public sealed record LineItemValue(string Id, int RowNumber, IReadOnlyList<FieldValue> Fields, IReadOnlyList<string> RowCitationIds);
+
+public sealed record BdxReviewPayload(
+    BdxDocument Document,
+    IReadOnlyList<SourceSpan> SourceSpans,
+    IReadOnlyList<FieldValue> Fields,
+    IReadOnlyList<LineItemValue> LineItems,
+    IReadOnlyList<ReconciliationCheck> Reconciliation);

src/Reva.Core/Settings/AppSettings.cs

@@ -8,7 +8,9 @@ public sealed record AppSettings(
     string ProductName,
     double ConfidenceLowMax,     // score below this renders as "Low"
     double ConfidenceMediumMax,  // score below this renders as "Medium"; at or above is "High"
-    Guid? DefaultTemplateId)
+    Guid? DefaultTemplateId,
+    double ReconciliationTolerance,
+    bool UseLlmAssist)
 {
-    public static AppSettings Default => new(AppTheme.Light, string.Empty, "Reve Intelligence", 0.6, 0.85, null);
+    public static AppSettings Default => new(AppTheme.Light, string.Empty, "Reve Intelligence", 0.6, 0.85, null, 0.01, false);
 }

src/Reva.Infrastructure/DocumentWorkflow.cs

@@ -3,6 +3,7 @@
 using Reva.Core.Contracts;
 using Reva.Core.Documents;
 using Reva.Core.Reinsurance;
+using Reva.Core.Settings;
 using Reva.Infrastructure.Extraction;
 using Reva.Infrastructure.Hashing;
 using Reva.Infrastructure.Parsing;
@@ -19,7 +20,9 @@ public sealed class DocumentWorkflow(
     IDocumentParser parser,
     IReinsuranceClassifier classifier,
     IReinsuranceExtractor extractor,
-    ISchemaMappingService schemaMapping) : IDocumentWorkflow
+    ISchemaMappingService schemaMapping,
+    ILlmFieldExtractor llmExtractor,
+    IExtractionMerger extractionMerger) : IDocumentWorkflow
 {
     private static readonly JsonSerializerOptions SerializerOptions = new(JsonSerializerDefaults.Web);
 
@@ -161,7 +164,11 @@ private async Task ParseAndExtractAsync(DocumentRecord record, CancellationToken
 
             // Always run best-effort extraction. Unknown/low-confidence documents are still
             // ingested as reviewable records (the extractor flags them) — never quarantined.
-            var extraction = extractor.Extract(parsed, classification);
+            var deterministic = extractor.Extract(parsed, classification);
+            var proposal = RuntimeSettings.Current.UseLlmAssist
+                ? await llmExtractor.ProposeAsync(parsed, deterministic, cancellationToken)
+                : null;
+            var extraction = extractionMerger.Merge(deterministic, proposal);
             var mapped = await schemaMapping.MapAsync(parsed, extraction.Fields, cancellationToken);
             record.Status = DocumentStatus.Extracted.ToString();
             record.DocumentType = extraction.DocumentType.ToString();
@@ -175,6 +182,33 @@ private async Task ParseAndExtractAsync(DocumentRecord record, CancellationToken
                 IsCorrected = field.IsCorrected
             }).ToList();
             record.SchemaMappings = mapped.Mappings.ToList();
+            record.SourceSpans = parsed.SourceSpans.Select(span => new DocumentSourceSpanRecord
+            {
+                SpanId = span.Id,
+                Page = span.Page,
+                PageWidth = span.PageWidth,
+                PageHeight = span.PageHeight,
+                Rotation = span.Rotation,
+                X = span.Bbox.X,
+                Y = span.Bbox.Y,
+                Width = span.Bbox.Width,
+                Height = span.Bbox.Height,
+                PolygonJson = JsonSerializer.Serialize(span.Polygon ?? [], SerializerOptions),
+                Text = span.Text,
+                OcrConfidence = span.OcrConfidence,
+                BlockId = span.BlockId,
+                TableId = span.TableId,
+                RowIndex = span.RowIndex,
+                ColumnIndex = span.ColumnIndex
+            }).ToList();
+            record.Pages = parsed.Pages.Select(page => new DocumentPageRecord
+            {
+                Page = page.Page,
+                ImagePath = page.ImagePath,
+                Width = page.Width,
+                Height = page.Height,
+                Rotation = page.Rotation
+            }).ToList();
             record.Tables = extraction.Tables.Select(table => new DocumentTableRecord
             {
                 Name = table.Name,
@@ -228,6 +262,8 @@ private static void ValidateFile(string fileName, Stream content)
             .Include(document => document.Fields)
             .Include(document => document.Tables)
             .Include(document => document.SchemaMappings)
+            .Include(document => document.SourceSpans)
+            .Include(document => document.Pages)
             .Include(document => document.Exceptions)
             .Include(document => document.ReviewEvents)
             .FirstOrDefaultAsync(document => document.Id == id, cancellationToken);

src/Reva.Infrastructure/Extraction/LlmExtractionOptions.cs

@@ -0,0 +1,18 @@
+namespace Reva.Infrastructure.Extraction;
+
+public sealed class LlmExtractionOptions
+{
+    public const string ProviderNone = "None";
+    public const string ProviderOllama = "Ollama";
+    public const string PromptVersion = "bdx-review-v1";
+    public const string SchemaVersion = "bdx-review-payload-v1";
+    public const string DefaultBaseUrl = "http://localhost:11434/v1";
+    public const string DefaultModel = "qwen3-vl:8b";
+    public const int MaxPromptCharacters = 8000;
+    public const int RetryPromptCharacters = 3000;
+    public const string SystemPrompt = "You extract reinsurance bordereaux fields and return strict JSON only.";
+    public string Provider { get; set; } = ProviderNone;
+    public string BaseUrl { get; set; } = DefaultBaseUrl;
+    public string Model { get; set; } = DefaultModel;
+    public bool DeterministicOnly { get; set; } = true;
+}