docs: sync architecture and examples

README.md

@@ -159,10 +159,13 @@ To swap embeddings instead, change `RAG_EMBEDDING_PROVIDER` and `RAG_EMBEDDING_M
 | `RAG_CHAT_PROVIDER` | `ollama` | chat adapter |
 | `RAG_EMBEDDING_PROVIDER` | `ollama` | embedding adapter |
 | `RAG_OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama API root |
+| `RAG_OPENAI_BASE_URL` | `http://localhost:1234/v1` | OpenAI-compatible API root |
+| `RAG_OPENAI_API_KEY` | empty | optional compatible-endpoint API key |
 | `RAG_CHAT_MODEL` | `llama3.2:3b` | generation model |
 | `RAG_EMBEDDING_MODEL` | `embeddinggemma` | embedding model |
 | `RAG_EVAL_MODEL` | `qwen3:8b` | optional local Ragas judge; should reliably follow tool schemas |
 | `RAG_DATA_DIR` | `data/qdrant` | persistent vector-store path |
+| `RAG_COLLECTION` | `documents` | Qdrant collection name |
 | `RAG_CHUNK_SIZE` | `900` | characters per chunk |
 | `RAG_CHUNK_OVERLAP` | `150` | repeated characters between chunks |
 | `RAG_EMBEDDING_BATCH_SIZE` | `32` | chunks embedded per provider request |

docs/index.html

@@ -133,7 +133,7 @@ <h2>System context</h2>
 
     <section id="flows">
       <div class="wrap">
-        <h2>Two explicit pipelines</h2>
+        <h2>Three explicit pipelines</h2>
         <div class="stack">
           <article class="card wide">
             <h3>Ingestion</h3>
@@ -158,6 +158,16 @@ <h3>Question answering</h3>
               <li>Render Markdown and citation markers deterministically, then return the retrieved proof.</li>
             </ol>
           </article>
+          <article class="card wide">
+            <h3>Evaluation data</h3>
+            <ol>
+              <li>Generate optional direct-fact synthetic silver candidates from stable source evidence.</li>
+              <li>Validate source support, answer support, schema integrity, and duplicate questions.</li>
+              <li>Review the source first, then approve, edit, or reject each candidate.</li>
+              <li>Freeze only <code>approved_gold</code> cases into a versioned release dataset.</li>
+              <li>Run deterministic retrieval, grounding, citation, and abstention gates; use Ragas only as a secondary diagnostic.</li>
+            </ol>
+          </article>
         </div>
       </div>
     </section>
@@ -207,7 +217,7 @@ <h2>Provider seams</h2>
         <h2>Data and retrieval model</h2>
         <div class="grid">
           <article class="card wide"><h3>Vector</h3><p>The embedding is stored with cosine distance. Collection dimensionality is discovered from the first embedding and checked thereafter.</p></article>
-          <article class="card wide"><h3>Payload</h3><p><code>document_id</code>, <code>source</code>, <code>page</code>, <code>chunk_index</code>, and <code>text</code> support citations, document filtering, deletion, and replacement on re-ingestion.</p></article>
+          <article class="card wide"><h3>Payload</h3><p><code>document_id</code>, <code>source_sha256</code>, <code>source</code>, <code>page</code>, <code>chunk_index</code>, and the actual chunk <code>text</code> support stable evidence anchors, citations, hybrid retrieval, document filtering, deletion, and replacement on re-ingestion.</p></article>
           <article class="card wide"><h3>Hybrid rank</h3><p>BM25Plus ranks stored chunk text while Qdrant ranks embeddings. Reciprocal-rank fusion combines positions, not incompatible raw score magnitudes.</p></article>
           <article class="card wide"><h3>Chunking</h3><p>PyMuPDF4LLM preserves PDF layout as Markdown; RapidOCR handles scanned pages locally; LangChain's standalone splitter preserves headings and natural text boundaries while enforcing configurable character limits.</p></article>
           <article class="card wide"><h3>Consistency rule</h3><p>Changing the embedding model or provider requires rebuilding the collection. Mixing vector spaces produces invalid similarity results.</p></article>

evaluation/cases.example.jsonl

@@ -1,2 +1,2 @@
-{"case_id":"notes-storage-001","dataset_version":"1.0.0","split":"smoke","corpus_id":"notes-demo","corpus_version":"1","question":"Where is the evidence stored?","question_type":"direct_fact","answerable":true,"expected_evidence":[{"source":"notes.txt","page":1,"contains":["stored locally"],"evidence_group":"storage"}],"required_facts":["stored locally"],"reference_answer":"The evidence is stored locally.","document_ids":[],"generation_method":"human","review_status":"approved_gold","tags":["direct_fact"]}
+{"case_id":"notes-storage-001","dataset_version":"1.0.0","split":"smoke","corpus_id":"notes-demo","corpus_version":"1","question":"Where is the evidence stored?","question_type":"direct_fact","answerable":true,"expected_evidence":[{"source":"notes.txt","source_sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","page":1,"contains":["stored locally"],"evidence_group":"storage"}],"required_facts":["stored locally"],"reference_answer":"The evidence is stored locally.","document_ids":[],"generation_method":"human","review_status":"approved_gold","tags":["direct_fact"]}
 {"case_id":"notes-absent-001","dataset_version":"1.0.0","split":"smoke","corpus_id":"notes-demo","corpus_version":"1","question":"Who approved the evidence?","question_type":"unanswerable","answerable":false,"expected_evidence":[],"required_facts":[],"reference_answer":null,"document_ids":[],"generation_method":"human","review_status":"approved_gold","tags":["unanswerable"]}