Release RAGForge v2.0 final

.github/workflows/ci.yml

@@ -13,5 +13,7 @@ jobs:
           python-version: "3.11"
           cache: pip
       - run: pip install -r requirements-dev.txt
-      - run: ruff check src tests app.py
+      - run: ruff check src tests scripts app.py
       - run: pytest -q
+      - run: python -m compileall -q src scripts app.py
+      - run: python scripts/release_check.py

CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+RAGForge used iterative numbered releases during development. v2.0.0 is the final planned portfolio release.
+
+## v2.0.0 - Final
+
+- polished product UI and final README/docs hierarchy
+- aligned the multi-hop Hard Mode case with the recommended Auto + Balanced semantic route
+- added final release verification tooling and CI consistency checks
+- fixed duplicate runtime-header presentation and cleaned architecture documentation
+- preserved the v1.9 adaptive retrieval, context-budget, compression, scale-stress and release-readiness architecture
+
+## v1.9 - Scale and release readiness
+
+- adaptive retrieval depth by corpus size
+- dynamic 2-5 chunk focused context budgets
+- focused sentence compression
+- 1x/5x/20x deterministic distractor-scale stress harness
+- prompt/context token economics
+- workspace diagnostics and release-readiness checklist
+
+## v1.8 - Context budget optimization
+
+- focused post-retrieval pruning
+- context/prompt telemetry
+- grounded-absence hardening
+- zero-Gemini context-budget ablation
+
+## v1.7 - Evaluation correctness and adaptive efficiency
+
+- Markdown-safe source cards and graphical node latency waterfall
+- grounded absence and improved citation scoring/repair
+- evaluation run provenance
+- measured small-corpus reranker skip policy
+
+## v1.6 - Hard Mode and analytical synthesis
+
+- `insight_synthesis` / `analytical` path
+- `[T#]` table citations
+- harder robustness benchmark
+- chunk-level reranker labels
+- optional profile benchmark and node latency summaries
+
+## v1.5 - Evaluation history and adaptive retrieval
+
+- saved Quick/Standard/Deep reports
+- incremental Deep evaluation
+- typed Text2SQL scoring
+- zero-call citation repair
+- adaptive reranking
+
+## v1.4 - Evaluation and API observability
+
+- proper evaluation score cards and quality gates
+- fixed retrieval AP metrics
+- API/architecture runtime inspection
+- cache-bypassed evaluation timing
+
+## v1.3 - Component evaluation
+
+- retrieval, citation, planner, SQL and latency metrics
+- reranker ablation
+- optional Deep judge
+
+## v1.2 - UX/lifecycle hardening
+
+- browser session continuity
+- lazy demo recovery
+- explicit abstention and workspace preflight
+- indexing/query progress improvements
+
+## v1.1 - Semantic routing redesign
+
+- schema-constrained semantic query analysis
+- source-profile index
+- global/hierarchical retrieval
+- correction before conditional web fallback
+
+## v1.0 - Initial production-style RAGForge
+
+- FastAPI + Gradio + LangGraph
+- hybrid dense/BM25 retrieval
+- reranking, HyDE, multi-query, CRAG, Self-RAG
+- Text2SQL, Ask-the-Web, citations, guardrails and Docker/Hugging Face deployment

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install run test lint docker
+.PHONY: install run test lint compile smoke verify docker
 
 install:
 	python -m pip install -r requirements-dev.txt
@@ -10,7 +10,17 @@ test:
 	pytest -q
 
 lint:
-	ruff check src tests app.py
+	ruff check src tests scripts app.py
+
+compile:
+	python -m compileall -q src scripts app.py
+
+smoke:
+	python scripts/release_check.py
+	pytest -q tests/test_v20_final.py tests/test_security.py tests/test_citations.py tests/test_eval_metrics.py
+
+verify: lint test compile
+	python scripts/release_check.py
 
 docker:
 	docker build -t ragforge .

README.md

@@ -10,391 +10,362 @@ pinned: false
 
 # RAGForge
 
-**RAGForge v1.9 - a production-style, portfolio-ready agentic RAG and analytical synthesis system for Hugging Face Spaces.**
+**RAGForge v2.0.0 - final portfolio release.**
+
+RAGForge is an evidence-first RAG system for **documents, structured tables, and the web**. It combines hybrid retrieval, semantic query planning, source-balanced and hierarchical search, analytical synthesis, read-only Text2SQL, corrective retrieval, conditional web research, explicit citations, adaptive context budgeting, and a built-in evaluation harness in one Dockerized FastAPI + Gradio application.
+
+The project is designed as a production-style portfolio system rather than a claim of production SaaS readiness. It makes retrieval decisions, evidence quality, citation provenance, evaluation tradeoffs, and runtime limitations visible instead of hiding them behind a chat box.
+
+## Verified pre-final benchmark
+
+The final release preserves the runtime architecture measured in the user-verified **v1.9 Standard** run. v2.0 changes benchmark alignment, UI, documentation, and release tooling; it does not claim a new provider-backed benchmark result before deployment.
+
+| Metric | Verified result |
+|---|---:|
+| Deterministic quality | **0.994 / Grade A** |
+| Answer accuracy | **100%** |
+| Source Recall@5 | **100%** |
+| Citation validity / coverage | **100% / 100%** |
+| Planner route / task / strategy | **100% / 100% / 100%** |
+| Text2SQL pass | **100%** |
+| Corpus overview pass | **100%** |
+| Adaptive context Recall@5 | **100%** |
+| Median adaptive context reduction | **41%** |
+| Evidence compression signal retention | **100%** |
+| Additional evidence-token reduction | **58%** |
+| Synthetic scale stress | **1,724 chunks / 24 sources** |
+| Scale-stress Recall@5 | **100%** |
+| Release readiness | **READY** |
+| Pipeline latency p50 / p95 | **1.79 s / 5.07 s** |
+
+See [`docs/FINAL_RESULTS.md`](docs/FINAL_RESULTS.md) for the full measured baseline, methodology caveats, and optimization findings.
+
+## Why RAGForge
+
+Most RAG demos collapse several different questions into one similarity search. RAGForge separates them:
+
+1. **What does the user mean?** A schema-constrained semantic planner identifies knowledge scope, task type, freshness, and retrieval strategy.
+2. **Where should the evidence come from?** Session-local documents, structured tables, the external web, or a mixed path.
+3. **How much evidence should reach generation?** Retrieval depth and generation context are adapted to corpus scale, retrieval confidence, source ambiguity, and task breadth.
+4. **Is the answer actually grounded?** Citations, evidence grading, grounded absence handling, optional Self-RAG verification, and transparent traces make the decision inspectable.
+5. **Did an optimization help?** The bundled benchmark separately measures retrieval, routing, SQL, citations, robustness, latency, context economics, and scale stress.
+
+That distinction is why a query such as **“What is the current corpus about?”** stays local, while **“Compare our NIST document with the latest guidance online”** can legitimately become a hybrid document + web task.
+
+## Core capabilities
+
+### Semantic planning and routing
+
+- `corpus`, `external`, `mixed`, and `structured_data` knowledge scopes
+- task types for fact lookup, overview, comparison, cross-document synthesis, aggregation, insight synthesis, and follow-up
+- retrieval strategies: `semantic`, `global`, `hierarchical`, `analytical`, `table`, and `none`
+- independent document and web queries
+- explicit `required | useful | irrelevant` web relevance
+- conversation-aware query rewriting
+- manual Auto / Documents / Web / Hybrid / Data(SQL) overrides
+
+### Retrieval
+
+- local FastEmbed dense embeddings with embedded Qdrant
+- BM25 lexical retrieval
+- reciprocal-rank fusion
+- source-profile index for source-first hierarchical retrieval
+- source-balanced global retrieval for corpus overviews
+- analytical document + DuckDB table evidence
+- adaptive cross-encoder reranker policy
+- corpus-scale adaptive retrieval depth
+- dynamic 2-5 chunk focused context budgets
+- deterministic focused sentence compression after retrieval
+
+### Grounded generation
+
+- document citations as `[D#]`
+- structured table citations as `[T#]`
+- web citations as `[W#]`
+- deterministic citation normalization and conservative repair
+- grounded-absence handling for genuinely missing information
+- optional CRAG correction loop
+- optional bounded Self-RAG-style verification and revision
+- confidence and complete pipeline trace
+
+### Structured data
+
+CSV/XLS/XLSX content is both indexed as text and loaded into an isolated in-memory DuckDB database. The Text2SQL path:
+
+- generates a single read-only query
+- validates `SELECT` / CTE-only SQL
+- blocks mutation/admin statements
+- enforces row limits
+- returns typed scalar/table results
+- is independently evaluated against expected computed values
 
-RAGForge combines hybrid document retrieval, source-level/hierarchical retrieval, semantic query planning, corrective RAG, Self-RAG-style verification, Text2SQL and an “Ask-the-Web” research path in one CPU-friendly application. The default LLM is **Google Gemini 3.5 Flash-Lite**; the UI also exposes Gemini 3.1 Flash-Lite and stronger Flash models.
-
-
-## What is new in v1.9
-
-v1.9 is the scale, context-economics and release-readiness release. It generalizes v1.8's successful fixed top-3 pruning into a corpus-aware policy and bundles the remaining production/evaluation work needed before treating RAGForge as a finished portfolio system. The new local ablations do not add Gemini requests.
-
-- **Adaptive retrieval depth** - candidate depth expands from 6 to 8/10/12 as corpus size grows, while broad tasks retain additional breadth.
-- **Dynamic 2-5 chunk context budgets** - focused local lookups choose their generation budget from corpus scale, retrieval confidence, score separation and source ambiguity instead of always keeping three chunks.
-- **Focused evidence compression** - a zero-LLM sentence selector trims only the generation copy of focused evidence; source cards and citation evidence retain the original chunks.
-- **Three-way context ablation** - Standard/Deep compare full top-k, the v1.8 fixed top-3 policy and the v1.9 adaptive budget. A second ablation measures adaptive context with/without sentence compression and checks labeled answer-signal retention.
-- **1x/5x/20x scale stress** - a deterministic distractor harness clones long-document chunks and reuses existing vectors to exercise the real hybrid retriever at roughly demo, medium and ~1000-chunk scale without embedding or Gemini cost.
-- **Overview/insight consistency** - the planner now enforces task/strategy structural consistency, while the overview evaluator accepts semantically richer insight synthesis only when route, breadth, citations and no-web behavior remain correct.
-- **Prompt and evidence economics** - traces expose retrieval depth, confidence/gap, context budget, compression, prompt/output/total token estimates and cited-source utilization.
-- **Pacing-corrected node latency** - evaluation node summaries remove deliberate free-tier pacing from model-service node time while preserving separate wall/pacing telemetry.
-- **Workspace health diagnostics** - capacity utilization, corpus scale, index readiness, estimated vector memory, TTL/idle age and evaluation-history counts are available in the Architecture + API tab and REST diagnostics endpoint.
-- **Release readiness** - Standard/Deep apply a transparent checklist across answer quality, grounding, routing, SQL, hard mode, adaptive-budget recall, compression retention and largest-scale stress recall.
-
-No new runtime dependency is introduced in v1.9.
-
-
-
-
-## What is new in v1.8
-
-v1.8 is a context-budget and generation-efficiency release driven by the v1.7 benchmark: Recall@5/Hit@1/MRR were saturated, citation quality reached 100%, but focused QA still carried distractor sources and generation dominated end-to-end latency. The release therefore reduces unnecessary model input without narrowing broad synthesis tasks.
-
-- **Adaptive focused context pruning** - focused local `fact_lookup`/`followup` queries using semantic or hierarchical retrieval keep a conservative three-chunk safety floor and drop only the low-value context tail. Overview, comparison, cross-document and insight/analytical tasks retain broad evidence.
-- **Context-budget trace telemetry** - Pipeline Inspector reports chunks, distinct sources, estimated context tokens and reduction percentage before/after pruning, plus the policy reason.
-- **Focused prompt budgeting** - ordinary corpus fact lookups no longer include the full session corpus manifest in the generation prompt after routing has already established scope. Broad/mixed tasks retain the manifest. Generation traces expose evidence-context size and estimated prompt tokens.
-- **Zero-call context-budget ablation** - Standard/Deep evaluation compare full top-k versus focused pruning on source Precision@5, Recall@5, Hit@1, MRR, context chunks/sources/chars/tokens and median reduction without spending any extra Gemini requests.
-- **Grounded-absence hardening** - Hard Mode missing-answer cases pass when either the natural-language absence matcher succeeds or the pipeline explicitly records `grounded_absence=true`, and the table exposes both signals.
-- **Reranker diagnostic aligned with runtime policy** - evaluation now states that small-corpus reranking is already skipped and treats the expensive cross-encoder run as an explicit ablation, not as the default recommendation.
-- **Focused efficiency telemetry in QA rows** - benchmark rows record pruning use, pre/post context size, manifest inclusion and estimated generation-prompt tokens so latency changes can be tied to actual input-budget changes.
-
-
-
-## What is new in v1.7
-
-v1.7 is an evidence-driven correctness, provenance and efficiency release based on the first full v1.6 Hard Mode/profile benchmark. It fixes evaluator/UI artifacts before changing retrieval behavior and turns measured profile/reranker results into explicit runtime policy.
-
-- **Markdown-safe source cards** - retrieved Markdown is rendered as escaped plain text inside uniform source cards, so a snippet beginning with `#` can no longer become a giant UI heading.
-- **Graphical latency waterfall** - Pipeline Inspector replaces ASCII `#####` bars with proportional HTML latency bars and exposes the reranker decision reason plus grounded-absence state.
-- **Grounded absence handling** - answers such as “the retrieved policy does not mention a dispute fee” are treated as calibrated no-answer responses instead of low-confidence hallucinations. This avoids unnecessary revise calls and gives Hard Mode a robust missing-answer matcher.
-- **Markdown-aware citation coverage** - numbered/bulleted claims count even when short, while generic list introductions/headings do not. This fixes false 0% coverage for answers such as the four NIST AI RMF functions.
-- **Table-source validity for overviews** - global corpus overviews surface deterministic DuckDB table evidence as `[T#]` sources, so structured claims can be cited validly instead of referring to a table ID absent from the source list.
-- **Fresh-vs-saved evaluation provenance** - each saved report gets a run ID and server-boot ID. Fresh execution messages are no longer overwritten by the saved-run selector, and saved-run loading is triggered only by explicit user input.
-- **Profile-policy summary** - optional Fast/Balanced/Agentic benchmarking now produces aggregated profile metrics and an evidence-scoped recommendation rather than only six raw rows.
-- **Context-efficiency diagnostics** - evaluation now calls out the case where Recall@5 is excellent but Precision@5 is low, separating “found the right source” from “sent too many distractors to generation”.
-- **Small-corpus reranker policy tightened** - because v1.6 showed identical source and chunk metrics with/without reranking while adding multi-second latency, the cross-encoder is skipped even in Agentic on small corpora. It remains available for larger corpora.
-- **Diagnostic readability** - each `Next:` recommendation starts on its own line.
-
-## What is new in v1.6
-
-v1.6 moves RAGForge from a mostly saturated demo benchmark into harder evaluation and analytical synthesis. The goal is to make the next improvements measurable rather than simply adding more RAG components.
-
-- **Insight Synthesis** - the semantic planner can classify `insight_synthesis` and choose an `analytical` retrieval strategy for questions such as “What does this collection reveal?” or “What trends stand out?”.
-- **Document + table analysis in one grounded answer** - analytical retrieval combines source-balanced original document evidence with deterministic DuckDB table summaries/rows. Table-derived claims are cited as `[T#]` alongside `[D#]` documents and `[W#]` web sources.
-- **Hard Mode benchmark** - Standard/Deep evaluation now includes paraphrase, distractor, missing-answer, multi-hop, local-freshness, structured filtering, analytical-synthesis and prompt-injection cases. Hard-mode performance contributes to the deterministic score and quality gates.
-- **Chunk-level reranker evaluation** - the explicit RRF vs cross-encoder ablation now reports chunk Hit@1/MRR on cases with auditable chunk-content labels, in addition to source-level metrics. This tests whether reranking helps *inside the correct source*, not only whether it finds the right file.
-- **Optional profile benchmark** - users can explicitly compare Fast, Balanced and Agentic on a small labeled subset, including accuracy, citation coverage, service latency, estimated LLM calls and reranker/correction usage. It is off by default to protect free-tier quota.
-- **Semantic citation attribution** - zero-call citation repair keeps its conservative lexical checks but can use the already-loaded local embedding model as a high-threshold fallback for clearly supported uncited claims.
-- **Node latency observability** - query inspection includes a dependency-free node-latency waterfall, and evaluation reports aggregate mean/p50/p95 timings per LangGraph node.
-- **Evaluation run history** - each completed run is timestamp-archived inside the workspace. The UI/API expose historical grade/score/citation/hard-mode/latency/request data plus deltas against the previous run of the same depth.
-- **v1.5.2 stability retained** - JSON-safe saved reports, table export, incremental Deep, quota pacing, typed Text2SQL evaluation, adaptive reranking and citation cleanup remain intact.
-
-## What is new in v1.5.2
-
-v1.5.2 is a narrow runtime hotfix over v1.5.1. It does not change retrieval, evaluation semantics, dependency pins or the demo benchmark.
-
-- **Quick/Standard/Deep evaluation crash fixed** - `pipeline.py` now explicitly imports the citation normalization and repair helpers introduced in v1.5.1. This fixes `NameError: name 'repair_missing_citations' is not defined` during generated-answer evaluation.
-- **Packaging regression coverage** - a dependency-free test now verifies the citation helpers are imported into the pipeline namespace, and the LangGraph-backed helper test invokes the repair path directly when optional runtime dependencies are available.
-- **v1.5.1 behavior retained** - saved-report JSON, table export, grouped-citation parsing and conservative citation repair are unchanged.
-- **Benchmark compatibility retained** - the benchmark remains `1.5.1` because this hotfix changes runtime wiring only, not benchmark questions or scoring semantics.
-
-## What is new in v1.5
-
-- **Saved evaluation history** - Quick, Standard and Deep reports are stored per workspace with model, benchmark version, corpus version and timestamp. The Evaluation tab can switch between saved runs instantly and compare them side by side without spending Gemini quota again.
-- **Incremental Deep evaluation** - when a matching Standard run is saved, Deep reuses that deterministic baseline and runs only the representative judge layer. A Standard → Deep workflow therefore drops from roughly 31 Deep-run requests to about 5 judge requests.
-- **Typed Text2SQL evaluation** - benchmark checks compare computed DuckDB scalar values directly, so booleans/numerics are judged as typed values rather than fragile Markdown strings. Correct SQL such as `weekend_support = true` is no longer penalized because of rendering differences.
-- **Adaptive reranking** - the cross-encoder remains available, but Fast mode and small/easy corpus queries skip it when the benchmark shows no measurable source-ranking gain. Comparison/cross-document work, larger corpora and Agentic mode can still use it.
-- **Zero-call citation repair** - an evidence-aware deterministic pass repairs only clearly supported uncited factual units, improving citation completeness without adding another Gemini call.
-- **Planner taxonomy refinement** - structured-data examples explicitly distinguish direct table lookups from cross-row min/max aggregation.
-- **Evaluation API history** - FastAPI can list and retrieve saved Quick/Standard/Deep reports, and `POST /api/v1/evaluate/demo` can reuse compatible cached evaluations.
-- **v1.4.1 quota protections retained** - rolling RPM pacing, provider-aware 429 backoff, pacing-aware latency, sampled Deep judging and request telemetry remain enabled.
-
-## The retrieval philosophy
-
-RAGForge separates three questions that simple RAG demos often collapse into one:
-
-1. **What does the user mean?** A schema-constrained semantic planner classifies knowledge scope, task type, freshness, retrieval strategy and independent document/web queries.
-2. **Where should evidence come from?** Uploaded/private corpus, structured tables, the external web, or a genuinely mixed task.
-3. **How should that evidence be retrieved?** Focused semantic chunk search, global source-balanced retrieval, hierarchical source-to-chunk retrieval, analytical document+table synthesis, Text2SQL, or web search.
-
-This matters for ambiguous language. For example, **“What is the current corpus about?”** is session-local: “current” modifies the indexed corpus and does *not* imply current-world freshness. Conversely, **“Compare our NIST document with the latest NIST guidance online”** is a mixed task and legitimately needs both document and web evidence.
-
-The behavior is learned/planned semantically; the application does not hard-code phrases such as “what is the corpus about”. Those phrases exist only as regression tests.
-
-## Why this is more than “chat with a PDF”
-
-### Semantic planning and task-aware routing
-- **Balanced/Agentic semantic query analyzer** with structured JSON output
-- distinguishes `corpus`, `external`, `mixed`, and `structured_data` knowledge scopes
-- task classification: fact lookup, overview, cross-document synthesis, comparison, aggregation, insight synthesis, follow-up
-- retrieval strategy selection: `semantic`, `global`, `hierarchical`, `analytical`, `table`, `none`
-- separate `document_queries` and `web_queries` instead of blindly sending the same string to every retriever
-- explicit `web_relevance = required | useful | irrelevant`
-- corpus manifest and recent conversation are supplied to the planner so pronouns/session-local references can be resolved
-- manual Auto/Documents/Web/Hybrid/Data(SQL) controls remain available and override the semantic route when selected
-
-### Hierarchical and global retrieval
-RAGForge maintains **two retrieval indexes per session**:
-
-1. **Chunk index** - normal evidence chunks for answer generation.
-2. **Source-profile index** - one compact, deterministic profile per ingested source, built from source metadata and representative excerpts.
-
-The source-profile index is retrieval-only; generated answers are still cited against original document chunks.
+### Ask-the-Web
 
-This supports:
-- **semantic retrieval** - dense + BM25 over all chunks for focused questions
-- **hierarchical retrieval** - source-profile retrieval first, then chunk retrieval restricted to selected sources
-- **global/source-balanced retrieval** - one query-relevant representative evidence chunk per source for corpus overviews and broad synthesis
-- source diversity for cross-document/comparison tasks, reducing long-document domination
+- DuckDuckGo keyless fallback
+- optional Tavily
+- optional Gemini Search grounding path
+- independently planned web queries
+- parallel fetch + main-text extraction
+- SSRF-oriented URL checks
+- local reranking and cited synthesis
+- web permission is separate from web relevance, so a weak local retrieval does not automatically leak a private corpus query to the internet
 
-A 48-page PDF therefore cannot monopolize an overview simply because it produced more chunks than four short files.
-
-### Hybrid search
-- local CPU embeddings with **FastEmbed / BAAI bge-small-en-v1.5**
-- embedded **Qdrant** vector store per user session
-- in-memory normalized embedding matrix for efficient source-scoped hierarchical search
-- **BM25** lexical retrieval
-- **reciprocal-rank fusion (RRF)**
-- local **cross-encoder reranking** (`Xenova/ms-marco-MiniLM-L-6-v2`) with an adaptive runtime policy: Fast/small-corpus cases can skip it when the measured latency cost is not justified, while harder/larger cases can retain it
-- sentence-aware chunking plus optional **semantic breakpoint chunking**
-- source/page metadata
-- suspicious retrieved prompt-injection text is down-weighted
-
-### Corrective RAG (CRAG)
-The corrective loop no longer means “low score → Google”. It is:
-
-`retrieve → task-aware evidence grade → correct/rewrite retrieval plan → retrieve again → re-grade → conditional web only if web is semantically relevant`
-
-Evidence grading considers:
-- dense/BM25 relevance signals rather than raw RRF or reranker logits
-- top-hit and top-3 evidence quality
-- lexical/semantic retriever agreement
-- distinct-source coverage when the task requires breadth
-- an optional semantic LLM grader for borderline/Agentic cases
-
-If a corpus-only query remains unsupported after correction, RAGForge can **abstain** instead of contaminating the answer with unrelated internet search.
+### File support
 
-### Better relevance observability
-Cross-encoder logits are useful for ranking but are not calibrated human probabilities. The UI therefore shows:
-- retrieval rank
-- bounded hybrid relevance signal from dense/BM25 evidence
-
-Raw RRF/dense/sparse/reranker values remain available in the returned source metadata/pipeline trace for debugging.
-
-### Agentic RAG
-- **LangGraph** state machine with conditional edges
-- history-aware semantic rewriting
-- optional **multi-query expansion**
-- optional **HyDE** hypothetical-document retrieval in Agentic mode
-- query correction/retrieval retry loop
-- **Self-RAG-style** answer audit and one bounded revision loop
-- response confidence score and full pipeline trace, including whether reranking was used and how many citations were deterministically repaired
-- process-level TTL response caching, isolated by session + corpus version
-- bounded exponential-backoff retries for transient Gemini API failures
+PDF, TXT, Markdown, DOCX, PPTX, CSV, XLS/XLSX, JSON, HTML, XML/YAML, code/text formats, common images, and ZIP archives.
 
-### Ask-the-Web
-- free/keyless **DuckDuckGo** fallback
-- optional Tavily provider
-- native Gemini Google Search provider using a separately configurable grounding submodel (`gemini-2.5-flash-lite` by default)
-- independently planned web queries
-- query fan-out, parallel page fetching, main-text extraction with Trafilatura, local reranking, Gemini synthesis and URLs in the source panel
-- SSRF-oriented URL checks; local/private network targets are rejected
-- web permission and web relevance are separate: checking **Allow web fallback** does not force web search
-
-### Documents and data
-- PDF, TXT, Markdown, DOCX, PPTX, CSV, XLS/XLSX, JSON, HTML, source-code/text formats, images and **ZIP archives**
-- safe ZIP extraction (path traversal, file-count, uncompressed-size and type limits)
-- page-aware PDF extraction
-- optional **Gemini OCR/document transcription** for scanned PDFs/images
-- CSV/XLSX indexed as text **and** loaded into isolated **DuckDB**
-- natural-language **Text2SQL** with single-statement read-only SQL validation and row limits
-- one-click bundled demo corpus
-
-### Production/demo engineering
-- **FastAPI** REST backend + **Gradio** UI in one Docker Space
-- optional Bearer auth for API write endpoints
-- per-session corpora and in-memory databases; TTL cleanup
-- UI + REST per-IP rate limiting
-- Prometheus `/metrics`
-- health/info/session/status/ingest/query/evaluation endpoints plus saved-evaluation listing/retrieval
-- no API keys committed to the repo
-- pytest tests + GitHub Actions CI
-- pipeline inspector exposes semantic plan, retrieval strategy, source selection, evidence grade, corrective plan, web decision, Self-RAG result and cache hits
+ZIP ingestion includes path-traversal, file-count, size, and extension controls. Optional Gemini OCR can transcribe scanned PDFs/images.
 
 ## Architecture
 
 ```mermaid
 flowchart TD
-    U[User / API] --> G[Input + upload guardrails]
-    G --> P{Semantic query planner}
-    P -->|structured data| SQL[Read-only DuckDB Text2SQL]
+    U[User / API] --> G[Input and upload guardrails]
+    G --> P{Semantic QueryPlan}
+    P -->|structured| SQL[Read-only DuckDB Text2SQL]
     P -->|external| W[Ask-the-Web]
-    P -->|corpus / mixed| RS{Retrieval strategy}
+    P -->|corpus or mixed| R{Retrieval strategy}
 
-    RS -->|semantic| C[Chunk index]
-    RS -->|global| GB[Source-balanced global retrieval]
-    RS -->|hierarchical| SP[Source-profile index]
-    SP --> SS[Select relevant sources]
-    SS --> C
+    R -->|semantic| C[Chunk index]
+    R -->|global| GB[Source-balanced retrieval]
+    R -->|hierarchical| SP[Source-profile index]
+    R -->|analytical| AN[Documents + deterministic table evidence]
+    SP --> C
 
-    C --> D[Dense FastEmbed/Qdrant]
+    C --> D[Dense FastEmbed / Qdrant]
     C --> B[BM25]
     D --> F[RRF]
     B --> F
-    F --> RP{Adaptive reranker policy}
-    RP -->|skip easy/small| E{Task-aware evidence grader}
-    RP -->|use harder/larger| X[Cross-encoder reranker]
-    GB --> E
-    X --> E
-
-    E -->|sufficient| A[Gemini generation]
-    E -->|weak, first attempt| CR[Correct query / strategy]
-    CR --> RS
-    E -->|weak + web relevant| W
-    E -->|weak + web irrelevant| AB[Abstain]
+    F --> RR{Adaptive reranker policy}
+    RR --> RD[Scale-aware retrieval depth]
+    RD --> CB{Adaptive context budget}
+    CB --> EC[Focused evidence compression]
+
+    GB --> EG{Evidence grade}
+    AN --> EG
+    EC --> EG
+    EG -->|sufficient| A[Grounded Gemini generation]
+    EG -->|weak first attempt| CR[Correct retrieval]
+    CR --> R
+    EG -->|external relevant| W
+    EG -->|unsupported local| AB[Abstain]
     W --> A
 
-    A --> V{Self-RAG audit}
-    V -->|revise once| RV[Faithfulness revision]
+    A --> V{Optional Self-RAG audit}
+    V -->|revise once| RV[Bounded revision]
     RV --> V
-    V -->|pass| O[Cited answer + sources + trace]
+    V --> O[Cited answer + sources + trace]
     SQL --> O
     AB --> O
+
+    O -. cache-bypassed benchmark .-> EV[Evaluation harness]
+    EV --> Q[Quality + robustness]
+    EV --> EFF[Context / compression / latency]
+    EV --> ST[1x / 5x / 20x scale stress]
+    Q --> READY[Release readiness]
+    EFF --> READY
+    ST --> READY
 ```
 
-## Deploy on Hugging Face Spaces
+The detailed Mermaid source lives in [`docs/architecture.mmd`](docs/architecture.mmd).
 
-1. Create a **Docker** Space.
-2. Extract/copy this repository into the Space repo root.
-3. In **Settings → Secrets**, add `GEMINI_API_KEY`; optionally `TAVILY_API_KEY` and `APP_API_TOKEN`.
-4. Push. The Dockerfile serves `uvicorn` on port `7860`.
-5. Leave **Use bundled demo files** checked and either click **Index corpus** or ask a non-Web question; v1.4 can lazily initialize the demo corpus. Then test the Balanced/Auto profile.
+## Quick start
 
-The Dockerfile explicitly owns `/tmp/ragforge` and model-cache directories as the non-root runtime user so per-session workspaces can be created safely on Hugging Face Spaces.
+### Hugging Face Spaces
+
+1. Create a **Docker** Space.
+2. Copy this repository into the Space root.
+3. Add `GEMINI_API_KEY` in **Settings -> Secrets**.
+4. Optionally add `TAVILY_API_KEY` and `APP_API_TOKEN`.
+5. Push the repository.
+6. Open the Space with **Use bundled demo files** enabled.
+7. Use the recommended **Auto + Balanced** profile.
 
-> **Public demo key warning:** public visitors consume your server-side Gemini quota. RAGForge adds per-IP limits, but a heavily shared Space should lower limits, add authentication, or require bring-your-own-key.
->
-> **Privacy caveat:** use only documents appropriate for the terms of the model/API tier you select.
+The bundled demo corpus can be indexed explicitly or initialized lazily on the first non-Web question.
 
-## Run locally
+### Local Docker
 
 ```bash
 cp .env.example .env
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -r requirements-dev.txt
-uvicorn app:app --reload --port 7860
+# add GEMINI_API_KEY to .env
+
+docker build -t ragforge .
+docker run --rm -p 7860:7860 --env-file .env ragforge
 ```
 
-Or:
+Open `http://localhost:7860`.
+
+### Python development
 
 ```bash
-docker build -t ragforge .
-docker run --rm -p 7860:7860 -e GEMINI_API_KEY=YOUR_KEY ragforge
+python -m pip install -r requirements-dev.txt
+make verify
+make run
 ```
 
-## API example
+`make verify` runs linting, tests, Python compilation, and the final release-consistency check.
 
-```bash
-curl -X POST http://localhost:7860/api/v1/session
+## Recommended demo flow
 
-curl -X POST http://localhost:7860/api/v1/ingest \
-  -F session_id=SESSION_ID \
-  -F files=@demo_documents/acme_cloud_runbook.md
+Start with the bundled corpus and **Auto + Balanced**:
 
-curl -X POST http://localhost:7860/api/v1/query \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "session_id": "SESSION_ID",
-    "query": "What is this corpus about?",
-    "config": {"mode": "Auto", "profile": "Balanced", "model": "gemini-3.5-flash-lite"}
-  }'
+```text
+What is the Sev-1 acknowledgement target?
+```
 
-curl -X POST http://localhost:7860/api/v1/evaluate/demo \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "session_id": "SESSION_ID",
-    "level": "Standard",
-    "model": "gemini-3.5-flash-lite",
-    "target_rpm": 12,
-    "reuse_saved": true,
-    "include_profile_benchmark": false
-  }'
+This demonstrates focused retrieval, adaptive context budgeting, sentence compression, a citation, and the latency waterfall.
+
+```text
+What is the collection about?
+```
+
+This demonstrates source-balanced global retrieval and document + table citations.
+
+```text
+What exactly does this collection reveal? Identify important trends and caveats.
 ```
 
-## Pipeline profiles
+This demonstrates `insight_synthesis -> analytical` retrieval with `[D#]` and `[T#]` evidence.
+
+```text
+Which support tier has the shortest first-response SLA?
+```
 
-| Profile | Intended use | Behavior |
-|---|---|---|
-| **Fast** | cheapest interactive path | narrow deterministic route, single document query, hybrid retrieval, answer generation |
-| **Balanced** | default portfolio UX | semantic structured planner, task-aware retrieval, optional borderline evidence grader, one corrective retrieval retry, conditional web, answer |
-| **Agentic** | showcases advanced RAG | semantic planner, multi-query, optional HyDE, semantic evidence grading, correction loop, conditional web, answer, Self-RAG verification and bounded revision |
+This demonstrates semantic routing into read-only Text2SQL.
 
-The feature switches remain independent so interviewers can see what each technique changes.
+A short portfolio/demo script is available in [`docs/PORTFOLIO_GUIDE.md`](docs/PORTFOLIO_GUIDE.md).
 
 ## Evaluation
 
-The built-in **Evaluation** tab is now a layered benchmark instead of a single smoke-test JSON dump. The labels live in `evals/demo_benchmark.json`, so the expected behavior is reviewable rather than hidden in evaluator prompts.
+RAGForge treats evaluation as part of the application rather than a notebook afterthought.
 
-### Standard deterministic metrics
+### Quick
 
-The original demo benchmark became nearly saturated by v1.5. v1.6 deliberately adds harder robustness cases so future changes must improve behavior rather than merely preserve an easy score.
+Small smoke test for deployment sanity.
 
+### Standard
 
-- focused answer-key accuracy
-- source Precision@5, Recall@5, MRR and AP@5
-- citation validity and sentence-level citation coverage across `[D#]`, `[T#]` and `[W#]` evidence
-- planner route, task and retrieval-strategy accuracy
-- web-use precision/recall and unnecessary-web rate
-- corpus-overview source coverage and no-unnecessary-web regressions
-- explicit empty-workspace abstention correctness
-- Text2SQL read-only SQL generation/execution checks; SQL routing is measured separately in the planner suite
-- service latency p50/p95, pacing/wall time, correction rate, runtime web-use rate, request count and estimated LLM calls
-- retrieval ablation comparing Hybrid RRF with Hybrid + local cross-encoder reranking, including chunk Hit@1/MRR on explicitly labeled cases
-- hard-mode robustness across paraphrase, distractor, missing-answer, multi-hop, insight-synthesis, structured filtering, local-freshness and prompt-injection cases
-- optional Fast/Balanced/Agentic profile benchmark for quality/latency/LLM-call tradeoffs
-- aggregated LangGraph node latency mean/p50/p95
-- timestamped evaluation history and score/latency deltas inside the current workspace
+Full deterministic suite covering:
 
-### Deep LLM-as-judge metrics
+- focused QA
+- route/task/strategy planning
+- web-use precision and recall
+- corpus overview
+- typed Text2SQL
+- abstention
+- Hard Mode robustness
+- retrieval + reranker ablation
+- adaptive context-budget ablation
+- evidence-compression ablation
+- node latency
+- synthetic 1x / 5x / 20x scale stress
+- release-readiness checklist
 
-Deep mode adds Gemini scores for **faithfulness, answer relevance, completeness and citation support** on a representative labeled sample, reducing free-tier request pressure while retaining diverse judge coverage. These judge scores are kept separate from deterministic metrics because an LLM judge is probabilistic and should not be treated as ground truth. The metric families mirror common RAG evaluation practice: retrieval quality is evaluated separately from generation faithfulness/relevance.
+### Deep
 
-The UI exposes **Quick**, **Standard** and **Deep** modes and renders a score card plus per-layer tables, with the full report still available as JSON. v1.5 saves the latest run of each depth per workspace, provides a side-by-side comparison table, and lets users switch among saved reports without rerunning. A compatible saved Standard report can act as the deterministic baseline for incremental Deep judging. The benchmark is intentionally small and corpus-specific; it is a regression/architecture-validation suite, not a claim of general RAG benchmark performance.
+Reuses a compatible saved Standard baseline when possible and adds a small calibrated Gemini judge sample. This keeps free-tier request pressure bounded.
 
-Evaluation defaults to **quota-safe pacing at 12 RPM**. The active Gemini limit is project/model specific, so use the value shown for your project in Google AI Studio and set the evaluation target below it. A Standard run uses typed one-call Text2SQL component checks; a Deep run after a compatible saved Standard normally needs only the representative judge calls rather than repeating the full deterministic benchmark.
+Evaluation uses rolling request pacing and honors provider 429 retry guidance. Saved Quick/Standard/Deep runs can be compared without rerunning them.
 
-## Model and dependency note
+See [`docs/EVALUATION.md`](docs/EVALUATION.md).
 
-The Space pins a compatible deployment set around Gradio 5 (`gradio==5.49.1`, `pydantic==2.11.10`, `google-genai==2.8.0`, `fastapi==0.116.1`) to avoid dependency-resolver conflicts while retaining the Gemini Interactions API used by RAGForge. Model names are still runtime-selectable in the UI.
+## REST API
 
-## ZIP support
+FastAPI exposes Swagger at `/docs` and OpenAPI at `/openapi.json`.
 
-ZIP upload is useful for testing a miniature knowledge base, but archives are treated as hostile input. Defaults cap compressed upload size, extracted file count, total uncompressed content and supported types; traversal paths are rejected.
+Key endpoints:
 
-## Privacy and persistence
+```text
+GET   /api/health
+GET   /api/v1/info
+POST  /api/v1/session
+GET   /api/v1/session/{session_id}
+GET   /api/v1/session/{session_id}/diagnostics
+POST  /api/v1/ingest
+POST  /api/v1/query
+POST  /api/v1/evaluate/demo
+GET   /api/v1/evaluation/benchmark
+GET   /api/v1/evaluation/saved/{session_id}
+GET   /api/v1/evaluation/history/{session_id}
+GET   /metrics
+```
+
+Example:
+
+```bash
+curl -X POST "$BASE_URL/api/v1/query" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "YOUR_SESSION_ID",
+    "query": "What is the collection about?",
+    "config": {"mode": "Auto", "profile": "Balanced"}
+  }'
+```
 
-The UI persists only an opaque session ID in browser local storage. Corpus contents, embeddings, DuckDB tables, chat history and saved evaluation reports remain server-side. A normal browser refresh can reconnect while the Space process is alive; a Hugging Face container restart still removes the in-memory/ephemeral workspace. Demo mode can rebuild automatically, while custom uploads and saved evaluations must be recreated after a restart.
+See [`docs/ARCHITECTURE_API.md`](docs/ARCHITECTURE_API.md).
+
+## Security model and honest limitations
+
+RAGForge demonstrates defense-in-depth controls for archive ingestion, retrieved prompt injection, SQL safety, SSRF-oriented web fetching, session isolation, secrets, and rate limiting. It is **not** a compliance-certified multi-tenant service.
+
+Important limitations:
+
+- workspace/vector/SQL state is process-local and ephemeral on a standard Space
+- browser persistence stores only an opaque workspace ID and does not make server data durable
+- large production deployments need durable tenant state, storage-level tenant filters, worker isolation, external vector/database infrastructure, and stronger egress controls
+- prompt-injection detection remains heuristic
+- token counts in traces are estimates for engineering comparison, not provider billing records
+- the 1,724-chunk scale result is a deterministic synthetic distractor stress test, not a substitute for a real enterprise corpus benchmark
+- free-tier Gemini quotas and data-use terms depend on the active provider project/tier
+
+See [`SECURITY.md`](SECURITY.md).
+
+## Repository map
+
+```text
+src/ragforge/
+  pipeline.py              LangGraph RAG orchestration
+  llm.py                   Gemini planning/generation/judging
+  retrieval.py             dense + BM25 + RRF + reranking
+  context_budget.py        adaptive retrieval/context policy
+  evidence_compression.py  focused local sentence compression
+  workspace.py             session corpus, indexes, SQL, eval history
+  evaluation.py            benchmark + diagnostics + readiness
+  stress_eval.py           zero-Gemini scale-stress harness
+  sql_agent.py             read-only Text2SQL
+  web_search.py            external research path
+  security.py              ingestion/query/web guardrails
+  ui.py                    Gradio application
+  api.py                   FastAPI surface
+
+evals/
+  demo_benchmark.json      transparent benchmark labels
+
+docs/
+  FINAL_RESULTS.md         verified pre-final benchmark
+  PORTFOLIO_GUIDE.md       demo and interview walkthrough
+  EVALUATION.md            evaluation methodology
+  ARCHITECTURE_API.md      architecture/API reference
+  FEATURE_MATRIX.md        feature inventory
+  QUERY_PLANNING.md        planner semantics
+  UX_LIFECYCLE.md          session/UI lifecycle
+  RESUME_BULLETS.md        concise project bullets
+```
 
-This public-demo build intentionally uses per-session ephemeral storage, embedded Qdrant and in-memory DuckDB. A real multi-tenant deployment should replace these with authenticated object storage, tenant-filtered managed retrieval, durable sessions and governed structured-data access.
+## Final project status
 
-## Enterprise migration path
+**v2.0.0 is the final planned feature release.** Future work should be driven by a genuinely larger real-world corpus or deployment requirement, not by adding more RAG acronyms.
 
-- Qdrant local → Qdrant Cloud / managed vector DB
-- in-process TTL cache → Redis
-- in-memory DuckDB → governed warehouse / Postgres read replica
-- process-local workspace registry → durable session/tenant service
-- local metrics → OpenTelemetry + centralized observability
-- simple API token → OAuth/OIDC + tenant-aware authorization
-- synchronous ingestion → object-storage events + workers
+The measured engineering conclusions are already useful:
 
-## Project documentation
+- source recall is saturated on the demo benchmark, so context economics mattered more than another retriever
+- the cross-encoder reranker was hundreds of times slower on the small demo with no measured source/chunk ranking gain, so runtime policy skips it there
+- adaptive context budgeting and sentence compression reduced generation input while preserving benchmark recall/signals
+- generation dominates latency, making prompt/context reduction more valuable than micro-optimizing millisecond retrieval
+- evaluation exposed multiple evaluator/UI bugs during development, demonstrating why the benchmark itself needed to be audited as carefully as the RAG pipeline
 
-- `docs/FEATURE_MATRIX.md` - implementation checklist and interview rationale
-- `docs/EVALUATION.md` - benchmark methodology, saved-run reuse, typed Text2SQL checks and quota behavior
-- `docs/QUERY_PLANNING.md` - semantic planner, hierarchical retrieval and CRAG policy
-- `docs/UX_LIFECYCLE.md` - browser/session lifecycle, lazy demo initialization and indexing UX
-- `docs/MIGRATION_1.3.md` - v1.2 to v1.3 upgrade notes
-- `docs/MIGRATION_1.4.md` - v1.3 to v1.4 upgrade notes
-- `docs/MIGRATION_1.4.1.md` - quota-safe evaluation and runtime-view stabilization patch
-- `docs/MIGRATION_1.5.md` - saved/incremental evaluation, typed Text2SQL checks and adaptive-reranking upgrade notes
-- `docs/ARCHITECTURE_API.md` - live architecture/API surface and endpoint examples
-- `docs/MIGRATION_1.2.md` - v1.1 to v1.2 upgrade notes
-- `docs/architecture.mmd` - Mermaid architecture source
-- `docs/RESUME_BULLETS.md` - resume-ready wording
-- `docs/DEMO_DATASETS.md` - corpus-extension ideas
-- `docs/SOURCES.md` - architectural references and official implementation docs
-- `SECURITY.md` - threat model and residual risk
+For project history, see [`CHANGELOG.md`](CHANGELOG.md).
 
 ## License
 
-MIT for this project’s source and synthetic demo files. Bundled/third-party documents retain their original terms.
+See [`LICENSE`](LICENSE).

SECURITY.md

@@ -1,5 +1,11 @@
 # Security model
 
+## v2.0 final security posture
+
+v2.0 does not add a new external execution surface. The final release keeps the existing archive, SQL, SSRF, session-isolation, prompt-injection, secret-handling and rate-limit controls, while clarifying operational limits in the README and portfolio documentation. `make verify` now includes a dependency-free release-consistency check so version/benchmark/documentation drift is caught in CI.
+
+The project remains a hardened **portfolio/demo** application, not a compliance-certified multi-tenant SaaS.
+
 ## v1.9 resource and scale controls
 
 v1.9 adds explicit workspace-health telemetry for chunk-cap utilization, corpus scale, approximate in-memory vector size, session TTL/idle age and index readiness. Adaptive retrieval depth remains bounded (up to 12 candidates by policy), focused generation budgets remain bounded (2-5 chunks), and sentence compression only changes the generator copy of retrieved text. The synthetic scale-stress evaluator reuses already-computed vectors and is isolated so a local stress-harness failure cannot crash the primary Standard/Deep report.
@@ -63,4 +69,4 @@ Saved evaluation metadata contains only operational provenance (short run ID, se
 
 ## Context pruning safety (v1.8)
 
-Focused context pruning is intentionally post-retrieval and task-scoped. It does not weaken prompt-injection scanning, source access controls, archive hardening or web SSRF protections. Broad/multi-source/analytical tasks bypass pruning, and the three-chunk safety floor is evaluated against source recall before the optimization is treated as successful.
+Focused context pruning is intentionally post-retrieval and task-scoped. It does not weaken prompt-injection scanning, source access controls, archive hardening or web SSRF protections. Broad/multi-source/analytical tasks bypass pruning, and the three-chunk safety floor is evaluated against source recall before the optimization is treated as successful.

docs/ARCHITECTURE_API.md

@@ -1,4 +1,8 @@
-# Architecture and API - v1.9
+# Architecture and API - v2.0 final
+
+## Final system shape
+
+v2.0 freezes the feature architecture around semantic routing, hybrid/source-balanced/hierarchical/analytical retrieval, adaptive context budgeting, focused evidence compression, Text2SQL, conditional web research, grounded generation, transparent traces, and component-level evaluation. The final release focuses on product presentation, benchmark alignment, documentation, and release verification rather than adding another retrieval subsystem.
 
 ## v1.9 adaptive scale and context pipeline
 
@@ -154,4 +158,4 @@ Evaluation cache metadata includes a short run ID and server-boot ID. These fiel
 
 The verify path now recognizes a grounded absence answer: an evidence-cited statement that the requested fact is not present in the selected sources. This state skips the normal low-confidence revise branch, preventing a second generation call whose only purpose would be to restate the same absence.
 
-For corpus overviews, structured tables are surfaced as deterministic `[T#]` evidence alongside the source-balanced document set. Analytical synthesis continues to use the same table evidence path.
+For corpus overviews, structured tables are surfaced as deterministic `[T#]` evidence alongside the source-balanced document set. Analytical synthesis continues to use the same table evidence path.

docs/EVALUATION.md

@@ -1,4 +1,10 @@
-# RAGForge evaluation - v1.9
+# RAGForge evaluation - v2.0 final
+
+## Final benchmark alignment
+
+v2.0 preserves the v1.9 deterministic evaluation architecture and bumps the benchmark to `2.0` because the multi-hop comparison Hard Mode case is now executed through the recommended `Auto + Balanced` semantic route. The case must resolve to `documents -> comparison -> hierarchical` and still satisfy the answer/retrieval labels. This prevents Fast mode's intentionally cheap fallback from being treated as the reference behavior for a multi-source reasoning test.
+
+The last provider-backed user-verified Standard baseline is documented in [`FINAL_RESULTS.md`](FINAL_RESULTS.md).
 
 ## v1.9 scale, compression and readiness evaluation
 
@@ -354,4 +360,4 @@ Citation evaluation accepts both one-ID-per-bracket syntax such as `[D1] [D2]` a
 syntax such as `[D1, D2]`. Runtime answer rendering normalizes grouped citations and removes
 duplicate trailing citation sets. The deterministic zero-call citation repair skips list-introduction
 or preamble lines ending in `:` so it does not attach a source merely because a broad introductory
-sentence overlaps many evidence snippets.
+sentence overlaps many evidence snippets.

docs/FEATURE_MATRIX.md

@@ -1,4 +1,6 @@
-# Feature matrix and design rationale
+# Feature matrix - v2.0 final
+
+The table below describes the final planned portfolio release. Future changes should be driven by real deployment/corpus requirements rather than feature-count growth.
 
 | Capability | RAGForge implementation | Why it matters |
 |---|---|---|
@@ -79,4 +81,4 @@ The demo uses embedded Qdrant, in-memory DuckDB, deterministic source profiles,
 
 | Evaluation provenance | run ID + server-boot ID + fresh/reused status | makes cache/rebuild behavior auditable and prevents fresh runs from being mistaken for saved reuse |
 | Context-efficiency diagnostics | source Precision@5 beside Recall@5 + targeted recommendations | exposes distractor-heavy context without sacrificing overview/synthesis breadth prematurely |
-| Grounded absence | evidence-cited missing-information answers skip unnecessary revise | rewards calibrated uncertainty and reduces extra model calls on unanswerable local questions |
+| Grounded absence | evidence-cited missing-information answers skip unnecessary revise | rewards calibrated uncertainty and reduces extra model calls on unanswerable local questions |

docs/FINAL_RESULTS.md

@@ -0,0 +1,88 @@
+# Final measured results
+
+This page records the **user-verified v1.9 Standard benchmark** immediately before the v2.0 final productization release. v2.0 preserves the measured runtime architecture but changes benchmark alignment for one multi-hop Hard Mode case, plus UI/docs/release tooling. Therefore these numbers are presented as the verified pre-final baseline rather than silently relabeled as a v2.0 provider-backed run.
+
+## Quality
+
+| Metric | Result |
+|---|---:|
+| Deterministic quality | 0.994 (Grade A) |
+| Answer accuracy | 100% |
+| Source Precision@5 | 48% |
+| Source Recall@5 | 100% |
+| Hit@1 | 100% |
+| MRR | 1.000 |
+| AP@5 | 1.000 |
+| nDCG@5 | 1.000 |
+| Citation validity | 100% |
+| Citation coverage | 100% |
+| Corpus overview pass | 100% |
+| Text2SQL pass | 100% |
+| Planner route/task/strategy | 100% / 100% / 100% |
+| Web precision/recall | 100% / 100% |
+| Hard Mode | 88% |
+| Release readiness | READY (100% critical gates) |
+
+The single v1.9 Hard Mode miss was the multi-hop Acme-vs-OrbitPay timing comparison. That case was being executed through Fast mode's cheap fallback even though the application recommendation is Auto + Balanced for semantic multi-source reasoning. v2.0 aligns that case with the recommended route and explicitly requires `comparison -> hierarchical` planning.
+
+## Context economics
+
+| Configuration | Precision@5 | Recall@5 | Median chunks | Median context tokens | Reduction |
+|---|---:|---:|---:|---:|---:|
+| Full top-k | 47.2% | 100% | 6 | 2,101 | 0% |
+| v1.8 fixed top-3 | 50.0% | 100% | 3 | 977 | 54.9% |
+| v1.9 adaptive budget | 48.1% | 100% | 4 | 1,099 | 41.0% |
+
+The final runtime keeps adaptive budgeting rather than the globally tighter fixed top-3 policy because it retains extra safety margin for ambiguous and larger-corpus cases.
+
+## Evidence compression
+
+| Configuration | Answer-signal retention | Median evidence tokens | Additional reduction |
+|---|---:|---:|---:|
+| Adaptive context only | 100% | 1,056 | 0% |
+| Adaptive + sentence compression | 100% | 503 | 58% |
+
+Compression modifies only the generation copy of retrieved evidence. Source cards and citation provenance retain the original retrieved chunks.
+
+## Scale stress
+
+The zero-Gemini synthetic stress harness reused existing long-document vectors and exercised the real hybrid retriever with distractor clones.
+
+| Scale | Chunks | Sources | Recall@5 | Hit@1 | MRR | Adaptive-pruned Recall@5 | Retrieval median |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Base | 90 | 5 | 100% | 100% | 1.000 | 100% | 5.5 ms |
+| +4x long-doc distractors | 434 | 9 | 100% | 100% | 1.000 | 100% | 7.5 ms |
+| +19x long-doc distractors | 1,724 | 24 | 100% | 87.5% | 0.938 | 100% | 48.2 ms |
+
+This is evidence that Recall@5 remained robust under synthetic distractor scale. It is not a substitute for a real enterprise corpus benchmark.
+
+## Reranker ablation
+
+The demo benchmark repeatedly found no source- or chunk-level ranking gain from the cross-encoder on the small corpus while retrieval latency increased by orders of magnitude. v1.9 measured roughly a **290x** retrieval-time multiplier in the explicit ablation.
+
+RAGForge therefore keeps the reranker available but skips it under the measured small-corpus policy. Larger corpora remain eligible because the demo does not prove the reranker is universally unnecessary.
+
+## Runtime
+
+| Metric | Result |
+|---|---:|
+| Pipeline p50 | 1.79 s |
+| Pipeline p95 | 5.07 s |
+| Planner p50 | 1.71 s |
+| Planner p95 | 1.84 s |
+| Mean estimated LLM calls | 0.76 |
+| Standard Gemini requests | 36 |
+| Evaluation target | 12 RPM |
+| 429 retries | 0 |
+
+Generation remained the dominant node by a wide margin, which motivated context/prompt optimization rather than further millisecond-scale retrieval tuning.
+
+## Interpretation
+
+The final engineering conclusions are more important than the headline grade:
+
+- retrieval recall is strong enough that **context selection** is now the more useful optimization surface
+- deterministic evaluation caught several bugs in the evaluator itself, including invalid AP calculations, missing table-citation sources, false citation-coverage failures, and missing-answer false negatives
+- measured reranker cost changed runtime policy rather than remaining a decorative architecture component
+- benchmark request pacing made evaluation repeatable under a 15-RPM free-tier project without 429 failures
+- the project exposes limitations rather than treating a synthetic stress run as proof of production scale

docs/MIGRATION_2.0.md

@@ -0,0 +1,42 @@
+# Migration to RAGForge v2.0.0
+
+v2.0 is the final planned feature release over v1.9. It is primarily a productization and benchmark-alignment release.
+
+## Runtime behavior
+
+The retrieval/generation architecture from v1.9 is preserved:
+
+- corpus-scale adaptive retrieval depth
+- dynamic 2-5 chunk focused context budgets
+- focused evidence sentence compression
+- source-balanced/global/hierarchical/analytical retrieval
+- adaptive reranker policy
+- CRAG/Self-RAG controls
+- Text2SQL and conditional web research
+
+The Hard Mode multi-hop comparison case is now evaluated through `Auto + Balanced` and must resolve to `comparison -> hierarchical`. This aligns the benchmark with the recommended semantic path.
+
+## UI
+
+- final v2.0 product hero and measured-baseline cards
+- Chat/Evaluation hierarchy simplified
+- recommended profile guidance surfaced
+- evaluation score-card metric tiles
+- duplicate Architecture runtime header fixed
+- final project-status footer
+
+## Documentation/release tooling
+
+- README rewritten as a finished product page
+- `CHANGELOG.md` added
+- `docs/FINAL_RESULTS.md` added
+- `docs/PORTFOLIO_GUIDE.md` added
+- `scripts/release_check.py` added
+- `make smoke` and `make verify` added
+- CI now runs compilation and the release consistency checker
+
+## Benchmark compatibility
+
+The benchmark version is `2.0`. Existing v1.9 saved reports remain historical and are not reused as current v2.0 Standard/Deep baselines.
+
+No new runtime dependency is introduced.

docs/PORTFOLIO_GUIDE.md

@@ -0,0 +1,116 @@
+# Portfolio and interview guide
+
+## 2-minute demo
+
+Use the bundled corpus with **Auto + Balanced**.
+
+### 1. Focused retrieval
+
+Ask:
+
+```text
+What is the Sev-1 acknowledgement target?
+```
+
+Show:
+
+- one-sentence grounded answer with `[D1]`
+- semantic route / fact lookup
+- adaptive context budget
+- evidence sentence compression
+- reranker skipped with an explicit policy reason
+- node latency waterfall
+
+Talking point: RAGForge separates retrieval depth from generation context. It can retrieve broadly enough for safety, then reduce what reaches the model.
+
+### 2. Global corpus overview
+
+Ask:
+
+```text
+What is the collection about?
+```
+
+Show:
+
+- source-balanced global retrieval
+- all five source families represented
+- `[D#]` document citations and `[T#]` table evidence
+- broad tasks bypass focused pruning/compression
+
+Talking point: long PDFs do not dominate simply because they create more chunks.
+
+### 3. Analytical synthesis
+
+Ask:
+
+```text
+What exactly does this collection reveal? Identify important trends and caveats.
+```
+
+Show:
+
+- `insight_synthesis -> analytical`
+- deterministic DuckDB table evidence combined with document evidence
+- quantitative table claims cited as `[T#]`
+
+Talking point: the analytical route is different from a generic document overview and can reason across text + structured data.
+
+### 4. Text2SQL
+
+Ask:
+
+```text
+Which support tier has the shortest first-response SLA?
+```
+
+Show the SQL route and typed result.
+
+Talking point: routing and SQL execution are independently evaluated. The SQL path is restricted to validated read-only queries.
+
+### 5. Evaluation
+
+Open Standard evaluation results and show:
+
+- component metrics instead of one opaque score
+- context-budget and compression ablations
+- scale stress
+- node latency
+- release readiness
+
+Talking point: evaluation findings changed runtime policy. For example, the small-corpus reranker is skipped because the ablation showed large latency cost without measured ranking gain.
+
+## 30-second architecture explanation
+
+> RAGForge first uses a schema-constrained planner to decide whether the question needs documents, SQL, the web, or a mixed path. Document retrieval can be semantic, source-balanced global, hierarchical source-to-chunk, or analytical document-plus-table retrieval. Dense and BM25 results are fused with RRF, then an adaptive policy decides retrieval depth, reranking, context budget, and focused sentence compression. Evidence is graded before generation, CRAG can retry retrieval, web search is conditional rather than automatic, and answers return explicit document/table/web citation IDs plus a full execution trace.
+
+## Strong engineering tradeoffs to discuss
+
+### Reranking
+
+The implementation contains a cross-encoder, but the runtime does not blindly pay for it. The demo ablation showed no source/chunk gain at small scale while adding multi-second retrieval latency, so the policy skips it there and preserves it for larger/harder workloads.
+
+### Context precision vs recall
+
+The demo reached 100% Recall@5 with modest Precision@5. Instead of lowering top-k globally, RAGForge retrieves enough candidates, then applies a generation-specific adaptive context budget. That preserves recall while reducing model input.
+
+### Free-tier evaluation
+
+A full benchmark can exceed provider RPM limits if every component fires immediately. RAGForge uses a rolling request pacer, honors retry guidance, stores reports, and lets Deep reuse Standard so evaluation itself is operationally realistic.
+
+### Evaluation bugs are real bugs
+
+During development, the evaluator itself produced invalid AP values, missed grouped citations, penalized list citations, and misclassified correct missing-information answers. Fixing the measurement system was part of the engineering work.
+
+## Honest limitations to mention
+
+- standard Hugging Face runtime state is ephemeral
+- no durable multi-tenant storage or distributed vector infrastructure
+- prompt-injection filtering is heuristic defense-in-depth
+- synthetic 1,724-chunk stress is not an enterprise-scale proof
+- token telemetry is estimated, not provider billing data
+- provider model quotas and privacy terms depend on the active tier/project
+
+## Resume-ready one-liner
+
+> Built RAGForge, a Dockerized FastAPI/Gradio agentic RAG system with semantic routing, hybrid + hierarchical retrieval, analytical document/table synthesis, read-only Text2SQL, conditional web research, adaptive context compression, cited answers, and an evaluation suite spanning robustness, citation quality, retrieval ablations, scale stress, latency, and release-readiness gates.

docs/QUERY_PLANNING.md

@@ -1,4 +1,8 @@
-# Semantic planning, hierarchical retrieval and corrective policy
+# Query planning - v2.0 final
+
+## Final planner contract
+
+The recommended general-purpose profile remains `Auto + Balanced`. v2.0 also aligns the multi-hop Hard Mode reference case with that semantic path so multi-source comparison is evaluated as `comparison -> hierarchical` rather than through Fast mode's intentionally cheap fallback. No phrase-specific production route was added.
 
 ## v1.9 task/strategy consistency and scale-aware retrieval
 
@@ -177,4 +181,4 @@ cross_document_synthesis
 analytical/global retrieval
 ```
 
-This separation prevents a latency optimization from silently redefining the user's information need. For focused fact lookups, generation also omits the full corpus manifest because the planner has already established corpus scope; broad and mixed tasks retain it.
+This separation prevents a latency optimization from silently redefining the user's information need. For focused fact lookups, generation also omits the full corpus manifest because the planner has already established corpus scope; broad and mixed tasks retain it.

docs/RESUME_BULLETS.md

@@ -1,3 +1,13 @@
+# Resume bullets - v2.0 final
+
+## Recommended final bullet
+
+- Built **RAGForge**, a Dockerized FastAPI/Gradio agentic RAG system with schema-constrained semantic routing, hybrid + hierarchical retrieval, analytical document/table synthesis, read-only Text2SQL, conditional web research, adaptive context compression, cited answers, and a benchmark covering retrieval, citations, robustness, scale stress, latency and release-readiness gates.
+
+## Measured supporting result
+
+- On the user-verified v1.9 Standard baseline, achieved 100% answer accuracy, Recall@5, citation validity/coverage, planner route/task/strategy accuracy and Text2SQL pass; adaptive context budgeting preserved 100% Recall@5 while reducing median context by 41%, with sentence compression retaining 100% labeled answer signals and cutting selected evidence tokens by a further 58%.
+
 - Extended RAGForge with an **Insight Synthesis** path that semantically distinguishes collection overviews from trend/pattern analysis, combines source-balanced document evidence with deterministic DuckDB descriptive context, and grounds structured claims with `[T#]` citations.
 - Evolved the evaluation suite into a **hard-mode robustness benchmark** covering paraphrase, distractors, missing answers, multi-hop reasoning, local freshness semantics, analytical synthesis, structured filtering and prompt-injection checks; added hard-mode quality gates.
 - Added **chunk-level reranker ablations** and an opt-in Fast/Balanced/Agentic profile benchmark, quantifying evidence quality, latency, LLM-call estimates, correction use and reranker tradeoffs rather than assuming more agentic steps are always better.

docs/SOURCES.md

@@ -1,4 +1,8 @@
-# Reference projects and implementation sources
+# Sources and implementation references - v2.0 final
+
+## Final-release note
+
+v2.0 introduces no new runtime dependency or external architectural component. The final changes are benchmark alignment, UI/documentation polish, and local release-verification tooling. Existing official/source references below continue to document the underlying Gradio, FastAPI, Gemini, LangGraph, Qdrant and retrieval behavior.
 
 No tutorial source code is copied into RAGForge. The requested projects were used as architectural inspiration/checklists.
 
@@ -75,4 +79,4 @@ v1.8 adds no new external benchmark or hosted dependency. The context-budget pol
 
 ## v1.9 implementation note
 
-v1.9 adds no external runtime dependency and no new third-party architecture source. Adaptive budgets, sentence compression, scale stress, workspace diagnostics and readiness scoring are implemented locally on top of the existing retrieval/evaluation stack. The scale harness reuses existing embedding vectors rather than calling an embedding or generation API.
+v1.9 adds no external runtime dependency and no new third-party architecture source. Adaptive budgets, sentence compression, scale stress, workspace diagnostics and readiness scoring are implemented locally on top of the existing retrieval/evaluation stack. The scale harness reuses existing embedding vectors rather than calling an embedding or generation API.

docs/UX_LIFECYCLE.md

@@ -1,4 +1,8 @@
-# RAGForge UI and workspace lifecycle
+# UX and lifecycle - v2.0 final
+
+## Final product polish
+
+v2.0 gives the UI a compact product hero, verified-baseline cards, clearer Chat/Evaluation hierarchy, recommended-profile guidance, evaluation metric cards, a cleaned runtime snapshot, and a final project-status footer. The underlying session/lazy-demo/indexing/query/evaluation lifecycle remains the same.
 
 ## v1.9 runtime health and capacity visibility
 
@@ -103,4 +107,4 @@ Saved evaluation switching is bound to user input rather than generic change eve
 
 Pipeline Inspector now exposes the focused context-budget decision directly after the reranker decision. For eligible fact lookups it shows chunks and estimated tokens before/after pruning plus reduction percentage. Broad tasks show a skip reason rather than a misleading zero.
 
-The Evaluation tab adds a **Context budget** table and export option. This ablation is deterministic and uses no additional Gemini calls, so users can inspect context-efficiency tradeoffs without increasing free-tier request pressure.
+The Evaluation tab adds a **Context budget** table and export option. This ablation is deterministic and uses no additional Gemini calls, so users can inspect context-efficiency tradeoffs without increasing free-tier request pressure.

docs/architecture.mmd

@@ -1,81 +1,69 @@
 flowchart TD
     U[User / API] --> UI{UI lifecycle state}
-    UI -->|demo selected + empty| DI[Lazy demo indexing]
-    UI -->|ready| G[Input guardrails]
+    UI -->|demo + empty| DI[Lazy demo indexing]
+    UI -->|ready| G[Input / upload guardrails]
     DI --> G
-    G --> P{Semantic QueryPlan}
+
+    G --> P{Schema-constrained QueryPlan}
     P --> PF{Workspace preflight}
     PF -->|missing local data| AB[Abstain]
     PF -->|structured data| SQL[Read-only Text2SQL / DuckDB]
     PF -->|external| W[Ask-the-Web]
-    PF -->|corpus or mixed| RS{Task-aware retrieval strategy}
+    PF -->|corpus or mixed| RS{Task-aware retrieval}
 
     RS -->|semantic| CI[Chunk index]
-    RS -->|global| GB[Source-balanced global evidence]
+    RS -->|global| GB[Source-balanced evidence]
     RS -->|hierarchical| SPI[Source-profile index]
-    RS -->|analytical| AN[Source-balanced docs + DuckDB analytical context]
-    SPI --> SEL[Semantic source selection]
-    SEL --> SCI[Source-scoped chunk search]
-    SCI --> CI
+    RS -->|analytical| AN[Documents + deterministic table evidence]
+    SPI --> SEL[Select sources]
+    SEL --> CI
 
     CI --> D[FastEmbed dense / Qdrant]
-    CI --> B[BM25 sparse]
+    CI --> B[BM25]
     D --> F[RRF]
     B --> F
     F --> RP{Adaptive reranker policy}
-    RP -->|skip when policy says RRF is enough| RD{Scale-aware retrieval depth}
-    RP -->|use for harder / larger tasks| X[Cross-encoder reranker]
-    X --> RD
-    RD --> CB{Adaptive 2-5 chunk context budget}
-    CB -->|focused lookup| EC[Query-focused sentence compression]
-    CB -->|broad task / disabled| EG{Task-aware evidence grader}
-    EC --> EG
+    RP --> RD[Corpus-scale retrieval depth]
+    RD --> CB{Adaptive 2-5 chunk budget}
+    CB -->|focused| CMP[Query-focused sentence compression]
+    CB -->|broad| EG{Evidence grade}
+    CMP --> EG
     GB --> EG
     AN --> EG
+
     EG -->|sufficient| A[Grounded Gemini generation]
-    EG -->|weak first attempt| COR[Correct queries / strategy]
+    EG -->|weak first attempt| COR[Correct retrieval plan]
     COR --> RS
-    EG -->|weak + web relevant + allowed| W
-    EG -->|weak + web irrelevant| AB
+    EG -->|external relevant + allowed| W
+    EG -->|unsupported local| AB
     W --> A
 
-    A --> V{Self-RAG verifier}
-    V -->|revise once| RV[Faithfulness revision]
+    A --> V{Optional Self-RAG audit}
+    V -->|revise once| RV[Bounded grounded revision]
     RV --> V
-    V -->|pass| O[Cited answer + sources + trace]
+    V --> O[Cited answer + sources + trace]
     SQL --> O
     AB --> O
 
-    O -. cache-bypassed fresh benchmark .-> EV[Evaluation harness]
-    EV --> ER[Bounded source metrics + reranker ablation]
-    EV --> CBA[Focused context-budget ablation]
-    EV --> EP[Planner / web-policy metrics]
-    EV --> EC[Citation + answer-key metrics]
-    EV --> ES[Text2SQL + abstention + latency]
-    EV --> HM[Hard-mode robustness]
-    EV --> PB[Optional profile benchmark]
-    EV --> NL[Node latency summary]
-    EV --> EJ[Calibrated Gemini Deep judge]
-    ER --> QG[Quality gates + diagnostics]
-    CBA --> QG
-    EP --> QG
-    EC --> QG
-    ES --> QG
-    EJ --> QG
-    HM --> QG
-    PB --> QG
-    NL --> QG
-    QG --> EH[Saved Quick / Standard / Deep reports]
-    EH --> CMP[In-app comparison + saved-report API]
-    EH --> HIST[Timestamped evaluation history + deltas]
-    EH -. compatible Standard baseline .-> EJ
-
-    API[FastAPI /docs + OpenAPI + Prometheus] -. live introspection .-> UI
-
-%% v1.8: focused local lookups can prune the distractor tail after ranking; broad synthesis retains full evidence breadth.
-
+    O -. cache-bypassed benchmark .-> EV[Evaluation harness]
+    EV --> RM[Source + chunk retrieval metrics]
+    EV --> CTX[Context budget / compression ablations]
+    EV --> PL[Planner / web policy]
+    EV --> CIT[Citation / answer checks]
+    EV --> SQ[Text2SQL / abstention]
+    EV --> HM[Hard Mode]
+    EV --> ST[1x / 5x / 20x scale stress]
+    EV --> LAT[Service node latency]
+    EV --> DJ[Optional calibrated Deep judge]
+    RM --> READY[Quality gates + release readiness]
+    CTX --> READY
+    PL --> READY
+    CIT --> READY
+    SQ --> READY
+    HM --> READY
+    ST --> READY
+    LAT --> READY
+    DJ --> READY
+    READY --> HIST[Saved runs + history + deltas]
 
-    O --> EV[Evaluation harness]
-    EV --> ST[Scale stress 1x / 5x / 20x]
-    EV --> CA[Context + compression ablations]
-    EV --> RR[Release-readiness checklist]
+    API[FastAPI /docs + OpenAPI + Prometheus] -. runtime introspection .-> UI

evals/README.md

@@ -1,4 +1,6 @@
-# RAGForge evaluation set
+# RAGForge benchmark - v2.0 final
+
+The final benchmark keeps the v1.9 retrieval/context/compression/scale methodology and changes one Hard Mode reference path: `hard_multihop_time_compare` now runs under `Auto + Balanced` and explicitly expects `documents -> comparison -> hierarchical`. This matches the recommended semantic runtime instead of using Fast mode as the reference for a multi-source comparison.
 
 ## v1.9 local ablations and scale stress
 
@@ -51,4 +53,4 @@ Citation coverage is Markdown-aware, missing-answer cases accept natural grounde
 
 Standard/Deep now add a deterministic `context_budget_ablation` table. It compares the original six-chunk focused context with the adaptive three-chunk safety floor and reports source Precision@5, Recall@5, Hit@1, MRR, median chunks/sources/chars, estimated tokens and reduction percentage. The ablation issues no Gemini requests.
 
-The missing-answer Hard Mode row also exposes `missing_answer_match` and `grounded_absence`. Either calibrated signal can satisfy the missing-information decision, avoiding false failures caused by one exact wording.
+The missing-answer Hard Mode row also exposes `missing_answer_match` and `grounded_absence`. Either calibrated signal can satisfy the missing-information decision, avoiding false failures caused by one exact wording.

evals/demo_benchmark.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.9",
-  "description": "RAGForge v1.9 benchmark with adaptive context budgets, deterministic evidence compression, synthetic larger-corpus stress evaluation, grounded-absence robustness, hard-mode cases, and source/chunk retrieval ablations.",
+  "version": "2.0",
+  "description": "RAGForge v2.0 final benchmark with adaptive context budgets, evidence compression, scale stress, grounded absence, hard-mode robustness, release readiness, and a default-profile multi-hop comparison case.",
   "qa_cases": [
     {
       "id": "qa_acme_sev1_ack",
@@ -341,7 +341,12 @@
       "relevant_sources": [
         "acme_cloud_runbook.md",
         "orbitpay_policy.txt"
-      ]
+      ],
+      "mode": "Auto",
+      "profile": "Balanced",
+      "expected_route": "documents",
+      "expected_task": "comparison",
+      "expected_strategy": "hierarchical"
     },
     {
       "id": "hard_insight_synthesis",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ragforge"
-version = "1.9.0"
+version = "2.0.0"
 description = "Production-style agentic RAG demo for Hugging Face Spaces"
 requires-python = ">=3.11"
 dependencies = []

scripts/release_check.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Dependency-free consistency checks for the final RAGForge release."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+APP_VERSION = "2.0.0"
+BENCHMARK_VERSION = "2.0"
+
+
+def read(path: str) -> str:
+    return (ROOT / path).read_text(encoding="utf-8")
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise SystemExit(f"RELEASE CHECK FAILED: {message}")
+
+
+def main() -> None:
+    pyproject = read("pyproject.toml")
+    init_py = read("src/ragforge/__init__.py")
+    api_py = read("src/ragforge/api.py")
+    ui_py = read("src/ragforge/ui.py")
+    readme = read("README.md")
+    benchmark = json.loads(read("evals/demo_benchmark.json"))
+
+    require(f'version = "{APP_VERSION}"' in pyproject, "pyproject version mismatch")
+    require(f'__version__ = "{APP_VERSION}"' in init_py, "package version mismatch")
+    require(f'version="{APP_VERSION}"' in api_py, "FastAPI version mismatch")
+    require(f'RAGForge v{APP_VERSION}' in ui_py, "UI version mismatch")
+    require(benchmark.get("version") == BENCHMARK_VERSION, "benchmark version mismatch")
+
+    require("—" not in ui_py and "–" not in ui_py, "UI contains long dash glyphs")
+    require("Final portfolio release" in ui_py, "final UI hero missing")
+    require("Verified pre-final benchmark" in readme, "final benchmark section missing from README")
+    require("v2.0.0 is the final planned feature release" in readme, "final project status missing")
+
+    required_docs = [
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "docs/FINAL_RESULTS.md",
+        "docs/PORTFOLIO_GUIDE.md",
+        "docs/EVALUATION.md",
+        "docs/ARCHITECTURE_API.md",
+    ]
+    for path in required_docs:
+        require((ROOT / path).is_file(), f"missing {path}")
+
+    demo_files = [
+        "acme_cloud_runbook.md",
+        "orbitpay_policy.txt",
+        "release_notes.html",
+        "support_matrix.csv",
+        "NIST_AI_RMF_1.0.pdf",
+    ]
+    for name in demo_files:
+        require((ROOT / "demo_documents" / name).is_file(), f"missing demo file {name}")
+
+    hard_cases = {case.get("id"): case for case in benchmark.get("hard_mode_cases", [])}
+    multihop = hard_cases.get("hard_multihop_time_compare", {})
+    require(multihop.get("mode") == "Auto", "multi-hop Hard Mode must use Auto")
+    require(multihop.get("profile") == "Balanced", "multi-hop Hard Mode must use Balanced")
+    require(multihop.get("expected_task") == "comparison", "multi-hop Hard Mode expected task mismatch")
+    require(multihop.get("expected_strategy") == "hierarchical", "multi-hop Hard Mode expected strategy mismatch")
+
+    # Catch an earlier UI regression where the live runtime header was duplicated.
+    architecture_fn = re.search(
+        r"def _architecture_snapshot\(.*?\n\s*return sid, runtime, curl, runtime_json",
+        ui_py,
+        flags=re.S,
+    )
+    require(architecture_fn is not None, "architecture snapshot function missing")
+    require(architecture_fn.group(0).count("**RAGForge:**") == 1, "runtime header is duplicated")
+
+    print(
+        "RAGForge release check PASS - "
+        f"app {APP_VERSION}, benchmark {BENCHMARK_VERSION}, final docs/UI/benchmark aligned."
+    )
+
+
+if __name__ == "__main__":
+    main()

src/ragforge/__init__.py

@@ -1,3 +1,3 @@
 """RAGForge: production-style agentic retrieval augmented generation demo."""
 
-__version__ = "1.9.0"
+__version__ = "2.0.0"

src/ragforge/api.py

@@ -29,7 +29,7 @@ def _auth(authorization: Annotated[str | None, Header()] = None) -> None:
 
 
 def create_api() -> FastAPI:
-    app = FastAPI(title="RAGForge API", version="1.9.0")
+    app = FastAPI(title="RAGForge API", version="2.0.0")
 
     @app.get("/api/health")
     def health():

src/ragforge/evaluation.py

@@ -824,7 +824,16 @@ def _hard_mode_eval(
             rows.append(row)
             continue
 
-        cfg = PipelineConfig(mode="Documents", profile="Fast", model=model, use_crag=False, allow_web_fallback=False, use_self_rag=False)
+        case_mode = str(case.get("mode") or "Documents")
+        case_profile = str(case.get("profile") or "Fast")
+        cfg = PipelineConfig(
+            mode=case_mode,
+            profile=case_profile,
+            model=model,
+            use_crag=bool(case.get("use_crag", False)),
+            allow_web_fallback=False,
+            use_self_rag=False,
+        )
         if kind == "insight":
             cfg = PipelineConfig(mode="Auto", profile="Balanced", model=model, use_crag=True, allow_web_fallback=False, use_self_rag=False)
         wait_before = request_pacer.total_sleep_seconds()
@@ -845,7 +854,34 @@ def _hard_mode_eval(
             passed = plan.get("task_type") == case.get("expected_task") and plan.get("retrieval_strategy") == case.get("expected_strategy") and float(evidence.get("source_coverage", 0.0) or 0.0) >= float(case.get("min_source_coverage", 0.0)) and (table_cited or not case.get("requires_table_citation"))
         else:
             passed = answer_key_match(result.answer, case) and float(retrieval.get("source_recall@5", 1.0)) >= 1.0
-        row.update({"route":plan.get("route"),"task":plan.get("task_type"),"strategy":plan.get("retrieval_strategy"),"answer_key_match":answer_key_match(result.answer,case) if kind=="qa" else None,"missing_answer_match":missing_answer_match(result.answer, case) if kind=="missing" else None,"grounded_absence":bool(result.trace.get("metrics",{}).get("grounded_absence",False)) if kind=="missing" else None,"citation_validity":round(float(citations["citation_validity"]),3),"citation_coverage":round(float(citations["citation_coverage"]),3),"source_recall@5":round(float(retrieval.get("source_recall@5",1.0)),3),"latency_ms":round(max(0.0,wall-pace),1),"pass":passed,"gemini_calls":int(result.trace.get("metrics",{}).get("llm_calls_estimate",0) or 0),"_answer":result.answer,"_sources":result.sources,"_node_times":_trace_node_times(result.trace, pace)})
+            expected_route = case.get("expected_route")
+            expected_task = case.get("expected_task")
+            expected_strategy = case.get("expected_strategy")
+            if expected_route:
+                passed = passed and plan.get("route") == expected_route
+            if expected_task:
+                passed = passed and plan.get("task_type") == expected_task
+            if expected_strategy:
+                passed = passed and plan.get("retrieval_strategy") == expected_strategy
+        row.update({
+            "evaluation_mode": cfg.mode if kind not in {"sql", "planner", "security"} else None,
+            "evaluation_profile": cfg.profile if kind not in {"sql", "planner", "security"} else None,
+            "route": plan.get("route"),
+            "task": plan.get("task_type"),
+            "strategy": plan.get("retrieval_strategy"),
+            "answer_key_match": answer_key_match(result.answer, case) if kind == "qa" else None,
+            "missing_answer_match": missing_answer_match(result.answer, case) if kind == "missing" else None,
+            "grounded_absence": bool(result.trace.get("metrics", {}).get("grounded_absence", False)) if kind == "missing" else None,
+            "citation_validity": round(float(citations["citation_validity"]), 3),
+            "citation_coverage": round(float(citations["citation_coverage"]), 3),
+            "source_recall@5": round(float(retrieval.get("source_recall@5", 1.0)), 3),
+            "latency_ms": round(max(0.0, wall - pace), 1),
+            "pass": passed,
+            "gemini_calls": int(result.trace.get("metrics", {}).get("llm_calls_estimate", 0) or 0),
+            "_answer": result.answer,
+            "_sources": result.sources,
+            "_node_times": _trace_node_times(result.trace, pace),
+        })
         rows.append(row)
     return rows
 

src/ragforge/ui.py

@@ -20,8 +20,18 @@ ROOT = Path(__file__).resolve().parents[2]
 DEMO_DIR = ROOT / "demo_documents"
 
 CSS = """
-#hero {max-width: 1200px; margin: 0 auto 8px auto;}
-#hero h1 {font-size: 2.35rem; margin-bottom: .25rem;}
+#hero {max-width: 1220px; margin: 0 auto 14px auto;}
+.hero-shell {padding: 20px 22px; border: 1px solid rgba(128,128,128,.22); border-radius: 16px; background: linear-gradient(135deg, rgba(99,102,241,.08), rgba(128,128,128,.03));}
+.hero-kicker {font-size: .78rem; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; opacity: .72;}
+.hero-title {font-size: 2.3rem; line-height: 1.05; font-weight: 780; margin: 5px 0 8px 0;}
+.hero-subtitle {font-size: 1rem; line-height: 1.55; max-width: 900px; opacity: .84;}
+.hero-badges {display: flex; flex-wrap: wrap; gap: 7px; margin-top: 13px;}
+.hero-badge {font-size: .79rem; padding: 5px 9px; border: 1px solid rgba(128,128,128,.25); border-radius: 999px; background: rgba(128,128,128,.06);}
+.baseline-grid {display: grid; grid-template-columns: repeat(4, minmax(120px, 1fr)); gap: 8px; margin: 10px 0 14px 0;}
+.baseline-card {padding: 10px 12px; border: 1px solid rgba(128,128,128,.2); border-radius: 11px; background: rgba(128,128,128,.035);}
+.baseline-label {font-size: .72rem; text-transform: uppercase; letter-spacing: .05em; opacity: .66;}
+.baseline-value {font-size: 1.12rem; font-weight: 720; margin-top: 2px;}
+.section-note {font-size: .88rem; opacity: .78; line-height: 1.45;}
 .muted {opacity: .75;}
 .status-ready {padding: 8px 10px; border-radius: 8px;}
 .status-line {padding: 8px 10px; border: 1px solid rgba(128,128,128,.25); border-radius: 8px; margin: 6px 0;}
@@ -35,6 +45,12 @@ CSS = """
 .latency-track {height: 9px; border-radius: 999px; background: rgba(128,128,128,.18); overflow: hidden;}
 .latency-fill {height: 100%; min-width: 2px; border-radius: 999px; background: var(--primary-500, currentColor);}
 .latency-time {font-size: .84rem; text-align: right; opacity: .8;}
+.eval-card-grid {display: grid; grid-template-columns: repeat(5, minmax(105px, 1fr)); gap: 8px; margin: 8px 0 14px 0;}
+.eval-card {padding: 10px 12px; border: 1px solid rgba(128,128,128,.2); border-radius: 10px; background: rgba(128,128,128,.035);}
+.eval-card-label {font-size: .70rem; text-transform: uppercase; letter-spacing: .045em; opacity: .65;}
+.eval-card-value {font-size: 1.05rem; font-weight: 720; margin-top: 2px;}
+.footer-note {text-align: center; opacity: .68; font-size: .82rem; padding: 15px 0 4px 0;}
+@media (max-width: 900px) {.baseline-grid,.eval-card-grid {grid-template-columns: repeat(2, minmax(120px, 1fr));}}
 """
 
 
@@ -189,9 +205,18 @@ def _eval_summary_markdown(report: dict[str, Any]) -> str:
     summary = report.get("summary", {}) if report else {}
     if not summary:
         return "*Run an evaluation to see the score card.*"
+    cards = (
+        '<div class="eval-card-grid">'
+        f'<div class="eval-card"><div class="eval-card-label">Grade</div><div class="eval-card-value">{html.escape(str(summary.get("quality_grade", "-")))}</div></div>'
+        f'<div class="eval-card"><div class="eval-card-label">Answer accuracy</div><div class="eval-card-value">{float(summary.get("answer_accuracy", 0.0)):.0%}</div></div>'
+        f'<div class="eval-card"><div class="eval-card-label">Recall@5</div><div class="eval-card-value">{float(summary.get("source_recall@5", 0.0)):.0%}</div></div>'
+        f'<div class="eval-card"><div class="eval-card-label">Citation coverage</div><div class="eval-card-value">{float(summary.get("citation_coverage", 0.0)):.0%}</div></div>'
+        f'<div class="eval-card"><div class="eval-card-label">Release readiness</div><div class="eval-card-value">{html.escape(str(summary.get("release_readiness", "-")))}</div></div>'
+        '</div>'
+    )
     lines = [
         f"### Evaluation score card - {summary.get('evaluation_level', '-')} - grade {summary.get('quality_grade', '-')}",
-        "",
+        cards,
         f"**Deterministic quality:** `{float(summary.get('deterministic_quality_score', 0.0)):.3f}` - "
         f"**answer accuracy:** `{float(summary.get('answer_accuracy', 0.0)):.0%}` - "
         f"**source Precision@5:** `{float(summary.get('source_precision@5', 0.0)):.0%}` - "
@@ -336,7 +361,7 @@ def _architecture_snapshot(session_id: str | None) -> tuple[str, str, str, dict[
     settings = get_settings()
     stats = ws.health_snapshot()
     runtime_json = {
-        "ragforge_version": "1.9.0",
+        "ragforge_version": "2.0.0",
         "workspace": stats,
         "models": {
             "generation": settings.default_model,
@@ -357,7 +382,7 @@ def _architecture_snapshot(session_id: str | None) -> tuple[str, str, str, dict[
     }
     runtime = (
         "### Live runtime\n"
-        f"**RAGForge:** `v1.9.0` - **workspace:** `{sid[:12]}...` - **status:** `{stats['status']}`\n\n"
+        f"**RAGForge:** `v2.0.0` - **workspace:** `{sid[:12]}...` - **status:** `{stats['status']}`\n\n"
         f"**Corpus:** `{stats['sources']}` sources - `{stats['chunks']}` chunks - "
         f"`{stats['source_profiles']}` source profiles - `{stats['tables']}` tables - "
         f"corpus version `{stats['version']}`\n\n"
@@ -504,17 +529,42 @@ def build_ui() -> gr.Blocks:
         else:  # Compatibility fallback for older Gradio builds.
             session_state = gr.State("")
 
-        gr.Markdown(
-            "# RAGForge - production-style agentic RAG\n"
-            "Hybrid search - analytical synthesis - reranking - HyDE - CRAG - Self-RAG - Text2SQL - Ask-the-Web - citations - evals - guardrails",
-            elem_id="hero",
+        gr.HTML(
+            """
+<div id="hero" class="hero-shell">
+  <div class="hero-kicker">RAGForge v2.0.0 - Final portfolio release</div>
+  <div class="hero-title">Evidence-first RAG for documents, tables and the web</div>
+  <div class="hero-subtitle">
+    Hybrid retrieval, semantic planning, analytical synthesis, read-only Text2SQL, conditional web research,
+    evidence citations, adaptive context budgets and a built-in evaluation harness in one Hugging Face Space.
+  </div>
+  <div class="hero-badges">
+    <span class="hero-badge">Auto + Balanced recommended</span>
+    <span class="hero-badge">Adaptive 2-5 chunk budgets</span>
+    <span class="hero-badge">[D#] [T#] [W#] citations</span>
+    <span class="hero-badge">Quick / Standard / Deep evals</span>
+    <span class="hero-badge">FastAPI + Gradio + LangGraph</span>
+  </div>
+</div>
+            """
+        )
+        gr.HTML(
+            """
+<div class="baseline-grid">
+  <div class="baseline-card"><div class="baseline-label">Verified answer accuracy</div><div class="baseline-value">100%</div></div>
+  <div class="baseline-card"><div class="baseline-label">Verified Recall@5</div><div class="baseline-value">100%</div></div>
+  <div class="baseline-card"><div class="baseline-label">Synthetic scale stress</div><div class="baseline-value">1,724 chunks</div></div>
+  <div class="baseline-card"><div class="baseline-label">Pre-final readiness</div><div class="baseline-value">READY</div></div>
+</div>
+<div class="section-note">Verified on the bundled v1.9 Standard benchmark. v2.0 keeps the measured retrieval/runtime architecture and finalizes benchmark alignment, UI, documentation and release tooling.</div>
+            """
         )
 
         with gr.Tabs():
-            with gr.Tab("Chat + RAG"):
+            with gr.Tab("Chat"):
                 with gr.Row():
                     with gr.Column(scale=4):
-                        gr.Markdown("### 1) Build a corpus")
+                        gr.Markdown("### Corpus")
                         uploads = gr.File(
                             label="Upload documents or a ZIP",
                             file_count="multiple",
@@ -538,9 +588,9 @@ def build_ui() -> gr.Blocks:
                             "No corpus indexed yet. Click **Index corpus**, or leave demo files enabled and ask a question."
                         )
 
-                        gr.Markdown("### 2) Retrieval controls")
+                        gr.Markdown("### Pipeline settings")
                         mode = gr.Dropdown(["Auto", "Documents", "Web", "Hybrid", "Data (SQL)"], value="Auto", label="Route")
-                        profile = gr.Radio(["Fast", "Balanced", "Agentic"], value="Balanced", label="Pipeline profile")
+                        profile = gr.Radio(["Fast", "Balanced", "Agentic"], value="Balanced", label="Pipeline profile", info="Balanced is the recommended default. Fast minimizes model calls; Agentic enables the richest corrective/verification behavior.")
                         model = gr.Dropdown(
                             ["gemini-3.5-flash-lite", "gemini-3.1-flash-lite", "gemini-3.6-flash", "gemini-3.5-flash"],
                             value=settings.default_model,
@@ -565,8 +615,10 @@ def build_ui() -> gr.Blocks:
                             top_k = gr.Slider(2, 12, value=6, step=1, label="Final context chunks")
 
                     with gr.Column(scale=7):
-                        chatbot = gr.Chatbot(label="RAG conversation", type="messages", height=510)
-                        query = gr.Textbox(label="Ask a question", placeholder="What does the corpus say about...?", lines=2)
+                        gr.Markdown("### Ask RAGForge")
+                        gr.Markdown("<small>Try: `What is the Sev-1 acknowledgement target?` - `What is the collection about?` - `Which support tier has the shortest SLA?`</small>")
+                        chatbot = gr.Chatbot(label="Conversation", type="messages", height=510)
+                        query = gr.Textbox(label="Question", placeholder="Ask about the indexed corpus, structured tables, or current web information...", lines=2)
                         ask_btn = gr.Button("Ask", variant="primary")
                         query_status = gr.Markdown("Ready.", elem_classes=["status-line"])
                         with gr.Accordion("Sources", open=True):
@@ -810,9 +862,19 @@ def build_ui() -> gr.Blocks:
 
             with gr.Tab("Evaluation"):
                 gr.Markdown(
-                    "### RAG evaluation benchmark\n"
-                    "Evaluate retrieval, routing, analytical synthesis, citations, abstention, Text2SQL, hard-mode robustness and runtime efficiency "
-                    "against the transparent bundled benchmark in `evals/demo_benchmark.json`."
+                    "### Evaluation lab\n"
+                    "RAGForge evaluates retrieval, routing, analytical synthesis, citations, abstention, Text2SQL, hard-mode robustness, "
+                    "context economics and scale stress against the transparent benchmark in `evals/demo_benchmark.json`."
+                )
+                gr.HTML(
+                    """
+<div class="baseline-grid">
+  <div class="baseline-card"><div class="baseline-label">Verified v1.9 grade</div><div class="baseline-value">A / 0.994</div></div>
+  <div class="baseline-card"><div class="baseline-label">Citations</div><div class="baseline-value">100% / 100%</div></div>
+  <div class="baseline-card"><div class="baseline-label">Context reduction</div><div class="baseline-value">41% + 58%</div></div>
+  <div class="baseline-card"><div class="baseline-label">20x stress recall</div><div class="baseline-value">100%</div></div>
+</div>
+                    """
                 )
                 eval_level = gr.Radio(
                     ["Quick", "Standard", "Deep"],
@@ -1262,4 +1324,7 @@ The letter grade uses quality gates so one weak subsystem cannot be hidden by a
                     show_progress="hidden",
                 )
 
+        gr.HTML(
+            '<div class="footer-note">RAGForge v2.0.0 - final portfolio release - evidence-first retrieval, transparent evaluation, explicit limitations.</div>'
+        )
         return demo

tests/test_evaluation_assets.py

@@ -5,7 +5,7 @@ from pathlib import Path
 def test_demo_benchmark_is_multilayer_and_auditable():
     path = Path("evals/demo_benchmark.json")
     data = json.loads(path.read_text(encoding="utf-8"))
-    assert data["version"] == "1.9"
+    assert data["version"] == "2.0"
     assert len(data["qa_cases"]) >= 9
     assert len(data["planner_cases"]) >= 10
     assert len(data["overview_cases"]) >= 2
@@ -49,7 +49,7 @@ def test_demo_evaluation_and_introspection_are_available_through_api():
     assert "/api/v1/session/{session_id}" in text
     assert "/api/v1/evaluation/saved/{session_id}" in text
     assert "/api/v1/evaluation/saved/{session_id}/{level}" in text
-    assert 'version="1.9.0"' in text
+    assert 'version="2.0.0"' in text
 
 
 def test_v15_evaluation_cache_and_incremental_deep_are_present():

tests/test_ui_copy.py

@@ -54,7 +54,7 @@ def test_ui_has_quota_safe_evaluation_controls_and_score_card_spacing():
 
 def test_architecture_snapshot_returns_complete_runtime_payload():
     text = Path("src/ragforge/ui.py").read_text(encoding="utf-8")
-    assert '"ragforge_version": "1.9.0"' in text
+    assert '"ragforge_version": "2.0.0"' in text
     assert "return sid, runtime, curl, runtime_json" in text
     assert "curl = f\ndef _eval_frame" not in text
 

tests/test_v16_features.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 def test_v16_benchmark_has_hard_mode_and_insight_plans():
     data = json.loads(Path("evals/demo_benchmark.json").read_text(encoding="utf-8"))
-    assert data["version"] == "1.9"
+    assert data["version"] == "2.0"
     assert len(data.get("hard_mode_cases", [])) >= 8
     insight = [c for c in data["planner_cases"] if c.get("task") == "insight_synthesis"]
     assert insight

tests/test_v20_final.py

@@ -0,0 +1,57 @@
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_v20_versions_and_final_release_assets_are_aligned():
+    assert 'version = "2.0.0"' in (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    assert '__version__ = "2.0.0"' in (ROOT / "src/ragforge/__init__.py").read_text(encoding="utf-8")
+    assert 'version="2.0.0"' in (ROOT / "src/ragforge/api.py").read_text(encoding="utf-8")
+    benchmark = json.loads((ROOT / "evals/demo_benchmark.json").read_text(encoding="utf-8"))
+    assert benchmark["version"] == "2.0"
+    assert (ROOT / "CHANGELOG.md").is_file()
+    assert (ROOT / "docs/FINAL_RESULTS.md").is_file()
+    assert (ROOT / "docs/PORTFOLIO_GUIDE.md").is_file()
+    assert (ROOT / "scripts/release_check.py").is_file()
+
+
+def test_v20_multihop_hard_case_uses_recommended_semantic_path():
+    benchmark = json.loads((ROOT / "evals/demo_benchmark.json").read_text(encoding="utf-8"))
+    case = next(c for c in benchmark["hard_mode_cases"] if c["id"] == "hard_multihop_time_compare")
+    assert case["mode"] == "Auto"
+    assert case["profile"] == "Balanced"
+    assert case["expected_route"] == "documents"
+    assert case["expected_task"] == "comparison"
+    assert case["expected_strategy"] == "hierarchical"
+
+
+def test_v20_hard_mode_evaluator_honors_case_profile_and_plan_expectations():
+    text = (ROOT / "src/ragforge/evaluation.py").read_text(encoding="utf-8")
+    assert 'case_mode = str(case.get("mode") or "Documents")' in text
+    assert 'case_profile = str(case.get("profile") or "Fast")' in text
+    assert 'expected_task = case.get("expected_task")' in text
+    assert 'expected_strategy = case.get("expected_strategy")' in text
+    assert '"evaluation_profile": cfg.profile' in text
+
+
+def test_v20_ui_is_productized_and_keeps_short_dash_constraint():
+    text = (ROOT / "src/ragforge/ui.py").read_text(encoding="utf-8")
+    assert "Final portfolio release" in text
+    assert 'with gr.Tab("Chat")' in text
+    assert "Evaluation lab" in text
+    assert "Verified answer accuracy" in text
+    assert "Release readiness" in text
+    assert "footer-note" in text
+    assert "—" not in text
+    assert "–" not in text
+
+
+def test_v20_readme_leads_with_product_and_measured_results_not_release_diary():
+    text = (ROOT / "README.md").read_text(encoding="utf-8")
+    assert "Verified pre-final benchmark" in text
+    assert "Core capabilities" in text
+    assert "Recommended demo flow" in text
+    assert "Final project status" in text
+    assert "What is new in v1.9" not in text
+    assert "CHANGELOG.md" in text