docs: reorganize into 8 buckets + 24 ADRs + master README (D-023)

Replaces the legacy flat docs/ layout with a numbered bucket structure
modeled on technical-repo conventions (e.g. Kubernetes docs/, IETF RFCs).
Old monolithic decisions.md (32 KB) split into 24 individual ADRs using
the Nygard template (Status / Context / Decision / Alternatives /
Consequences / Revisit-at-scale).

Structure:
docs/00-overview/ — problem statement, roadmap
docs/10-architecture/ — system, stack rationale, safety, scoring
docs/20-data-pipeline/ — ingestion policy, information source map
docs/30-engineering/ — needs-analysis flow, discovery script
docs/40-evaluation/ — eval methodology
docs/50-operations/ — (placeholder; runbooks land here)
docs/60-decisions/ — 24 ADRs + index README + legacy archive
docs/70-reference/ — (placeholder; glossary + indexes land here)

All 14 existing docs moved via git mv (history preserved):
01-requirements.md → 00-overview/problem-statement.md
02-architecture.md → 10-architecture/system-overview.md
03-eval-plan.md → 40-evaluation/eval-methodology.md
04-failure-modes.md → 10-architecture/safety-architecture.md
05-needs-analysis-flow.md → 30-engineering/needs-analysis-flow.md
ROADMAP.md → 00-overview/roadmap.md
decisions.md → 60-decisions/legacy-decisions-monolith.md
discovery-script.md → 30-engineering/discovery-script.md
information_source_map.md → 20-data-pipeline/information-source-map.md
ingestion_policy.md → 20-data-pipeline/ingestion-policy.md
scorecard-{methodology,knowledge-graph,tie-breaker-rubric}.md
→ 10-architecture/scoring-*.md
tech-stack-rationale.md → 10-architecture/stack-rationale.md

24 new ADRs (ADR-001 through ADR-024):
001 vertical-slice-scope · 002 health-category-vertical
003 curated-corpus · 004 hybrid-structured-vector
005 nextjs-fastapi-frontend · 006 sarvam-first-stack
007 illustrative-pricing · 008 consultative-advisor-persona
009 19-insurer-comprehensive-schema · 010 secret-handling
011 bge-local-embeddings · 012 render-then-hf-space-deploy
013 tailwind-shadcn-ui · 014 groq-llama-grader
015 openapi-typescript-codegen · 016 hybrid-brain-router
017 irdai-corpus-playwright-rescue · 018 chunk-size-sweep-deferred
019 nim-single-provider-consolidation · 020 code-data-split-hf-dataset
021 view-aware-system-prompt · 022 conversational-profile-updates
023 admin-panel-ip-gated · 024 triple-mirror-code-and-data

Superseded ADRs (006, 012, 014, 016) link to their replacements.

Master README.md rewritten as the project bible:
§1 60-second pitch
§2 vision + requirements + success criteria
§3 two parallel flows (customer journey vs. tech-flow)
§4 exhaustive tech architecture (diagrams + per-component table)
§5 data architecture (corpus + ingestion + storage topology)
§6 quality + safety (4-gate faithfulness + Indic drift gates)
§7 document ecosystem guide (per-bucket map)
§8 quick start + local dev
§9 deployment + storage topology
§10 rebuild-from-scratch instructions for a fresh Claude Code session

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -7,79 +7,798 @@ sdk: docker
 app_port: 7860
 pinned: false
 license: mit
-short_description: Voice AI advisor for Indian health insurance
+short_description: Voice AI advisor for Indian health insurance — grounded, cited, BFSI-compliance-grade
 ---
 
 # Insurance Sales Portfolio Expert
 
-A voice-first AI advisor for Indian health insurance buyers, over a curated corpus of 190 policy PDFs (plus 18 regulatory documents) from 19 leading insurers. Built as a take-home assignment for Sarvam AI.
+**A voice-first, BFSI-compliance-grade AI advisor for Indian health insurance.** Built as a Sarvam AI take-home, deployed on HuggingFace Spaces, with grounding, citations, faithfulness gates, and a curated 208-document corpus.
 
-**Live demo:** *(deployed URL — added at submission)*
+| | |
+|---|---|
+| **Live demo** | https://rohitsar567-insurancebot.hf.space |
+| **Code (production)** | [`huggingface.co/spaces/rohitsar567/InsuranceBot`](https://huggingface.co/spaces/rohitsar567/InsuranceBot) · [`github.com/rohitsar567/insurance-sales-bot`](https://github.com/rohitsar567/insurance-sales-bot) |
+| **Data (corpus + vectors)** | [`huggingface.co/datasets/rohitsar567/insurance-bot-data`](https://huggingface.co/datasets/rohitsar567/insurance-bot-data) · [`github.com/rohitsar567/insurance-sales-bot-data`](https://github.com/rohitsar567/insurance-sales-bot-data) (LFS) |
+| **Author** | Rohit Saraf · rohitsar567@gmail.com |
+| **Read time** | ~20 minutes (this doc) · or jump to [§7 Document Ecosystem Guide](#7-document-ecosystem-guide) |
 
-**Docs (read in order):**
+---
+
+## Table of Contents
+
+1. [Sixty-second pitch](#1-sixty-second-pitch)
+2. [Project vision & requirements](#2-project-vision--requirements)
+3. [Two parallel flows — customer vs. technology](#3-two-parallel-flows)
+4. [Exhaustive tech architecture](#4-exhaustive-tech-architecture)
+5. [Data architecture — corpus, extraction, embeddings](#5-data-architecture)
+6. [Quality & safety — eval, faithfulness, refusal](#6-quality--safety)
+7. [Document ecosystem guide](#7-document-ecosystem-guide)
+8. [Quick start & local development](#8-quick-start--local-development)
+9. [Deployment & storage topology](#9-deployment--storage-topology)
+10. [What a fresh Claude Code session needs to rebuild this](#10-rebuild-from-scratch)
+
+---
+
+## 1. Sixty-second pitch
+
+A **voice-first health-insurance advisor** for Indian buyers, grounded in a curated corpus of **208 documents** — 190 product documents from 19 leading insurers plus 18 IRDAI / regulatory documents — extracted into a 48-field structured schema with a rules-based A–F scorecard and a **4-gate hallucination defense** on every reply.
+
+The bot is **consumer-facing in experience, B2B in commercial application.** The realistic deployment is an insurer or aggregator white-labelling this advisor on top of Sarvam's ASR/TTS/LLM stack. The build deliberately optimises for the artifacts a BFSI buyer would audit: provenance, refusal behaviour, eval rigor, citation grammar.
+
+**Try on the live demo:** *"What's the pre-existing disease waiting period under Care Supreme, and how does that compare to ICICI Elevate?"* — comparative answer with `[Source: ...]` citations linking to specific policy PDFs and page ranges, brain tag showing which model handled it, audio synthesised by Sarvam Bulbul. Ask the same in Hinglish — *"Care Supreme mein PED ka waiting period kya hai?"* — and the response flows through the Indic translation cascade with three drift checks.
+
+---
+
+## 2. Project vision & requirements
+
+### 2.1 The problem
+
+Indian health insurance has 19+ insurers, 250+ products, and a regulatory layer (IRDAI master circulars, Insurance Act 1938) that materially overrides individual policy clauses. Buyers face:
+
+- **Information asymmetry** — premiums are hidden behind callback flows; product wordings are 60-page PDFs.
+- **Comparison fatigue** — features named differently across insurers (room-rent cap vs. category-of-room limit vs. accommodation eligibility — same thing).
+- **Mis-selling risk** — agents are paid on conversion; advice is rarely consultative.
+- **Regulatory complexity** — IRDAI mandates (waiting periods, free-look windows, standard exclusions) override insurer-specific clauses.
+
+### 2.2 What we built
+
+A **voice-first conversational advisor** that:
+
+- **Listens** in English, Hindi, or Hinglish (Sarvam Saarika v2.5 STT).
+- **Grounds** every factual claim in a retrieved PDF clause with `[Source: ...]` citation.
+- **Refuses** when the corpus doesn't have the answer (4 faithfulness gates).
+- **Compares** policies side-by-side using a 48-field structured schema.
+- **Scores** each policy A–F via a rules-based scorecard (24 of 48 fields → 6 sub-scores).
+- **Personalizes** — once the user shares profile info (age, dependents, income, conditions), scorecards re-compute and chat answers ground against the user's situation.
+- **Speaks** in the user's language (Sarvam Bulbul v2 TTS), with three Indic drift gates checking the translated reply preserves numbers, citations, and meaning.
+
+### 2.3 Success criteria (and current state)
+
+| Goal | v1 status |
+|---|---|
+| Voice-first, push-to-talk | ✓ live |
+| Hindi/Hinglish bidirectional | ✓ live (Sarvam translation cascade + 3 drift gates) |
+| Cited answers grounded in PDFs | ✓ live (4-gate faithfulness) |
+| Cross-policy comparison | ✓ live (DuckDB structured + Chroma vectors) |
+| Personalised scorecards | ✓ live (profile RAG — profile becomes a vector chunk) |
+| Refusal precision (refuse > mis-cite) | ✓ live (Gate 1-4, with 12/25 eval questions blocked — the safe failure mode) |
+| Regulatory grounding (IRDAI) | ✓ live (after Playwright rescue past Akamai bot protection — [ADR-017](docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) |
+| Admin LLM control panel | ✓ live (in-app tab, IP+password gated — [ADR-023](docs/60-decisions/ADR-023-admin-panel-ip-gated.md)) |
+
+### 2.4 Explicit non-goals (v1)
+
+- **Real-time quotes** — premiums are illustrative bands with disclaimer ([ADR-007](docs/60-decisions/ADR-007-illustrative-pricing.md)).
+- **Medical advice** — bot answers coverage questions, never clinical ones (persona rule 4).
+- **Full-duplex streaming voice** — v1 is push-to-talk; full-duplex is v2.
+- **Life / motor insurance** — v1 is health-only; v2 generalises ([ADR-002](docs/60-decisions/ADR-002-health-category-vertical.md)).
+- **Sentiment classifier on raw scraped reviews** — IRDAI complaint numbers are primary-source; sentiment labels are curated snippet roll-ups, not LLM-extracted.
+
+---
+
+## 3. Two parallel flows
+
+The bot is two flows running together — the customer's experience and the technology underneath. They are intentionally separated below so a reviewer can scan either.
+
+### 3A. Customer / Process Flow
+
+What a buyer experiences, end to end.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 1.  Land on the bot                                                │
+│  -------                                                                  │
+│  · Sees: chat panel + Marketplace · Premium · Profile · Admin tabs       │
+│  · Suggested questions in the chat box                                   │
+│  · "Voice reply" + "Hands-free" toggles in the input area                │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 2.  Ask the first question (text or voice)                          │
+│  -------                                                                  │
+│  · "Suggest a health insurance plan for me"                              │
+│  · Bot recognizes fact-find intent → asks: "First, your age?"            │
+│  · Conversational onboarding: age → dependents → income → primary goal   │
+│    → location → parents-to-insure → health conditions → budget           │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 3.  Profile-driven personalization unlocks                         │
+│  -------                                                                  │
+│  · Completeness bar reaches ≥60% → "personalized scores unlocked"        │
+│  · Marketplace tab now shows per-policy A-F grades RE-COMPUTED for       │
+│    this user's specific situation                                        │
+│  · Chat references your profile inline ("at 32 with 1 dependent…")       │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 4.  Free-form questions with citations                              │
+│  -------                                                                  │
+│  · "What's the room rent cap on Care Supreme?"                            │
+│  · "Compare cataract waiting in HDFC Optima vs ICICI Elevate"             │
+│  · Every factual claim gets [Source: <policy>, p.<page>] citation        │
+│  · Click a citation → opens the policy detail modal                       │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 5.  Conversational profile updates (mid-chat)                       │
+│  -------                                                                  │
+│  · User says: "I was just diagnosed with diabetes"                        │
+│  · Bot silently extracts → updates session.profile → re-upserts profile  │
+│    chunk → completeness bar ticks up → scores refresh                    │
+│  · No form-filling required mid-conversation                              │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 6.  View-aware grounding (the copilot effect)                       │
+│  -------                                                                  │
+│  · User opens a policy detail modal                                       │
+│  · Asks "What's the waiting period on this?"                              │
+│  · Bot resolves "this" → answers without re-stating policy name          │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 7.  Refusal as a feature                                            │
+│  -------                                                                  │
+│  · User: "Does this policy cover space-tourism injuries?"                 │
+│  · Bot: "I'd rather not answer that without stronger evidence in the     │
+│    policy documents I have."                                              │
+│  · The SAFE failure mode in BFSI is refuse > mis-cite                    │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 8.  Hindi / Hinglish flow                                           │
+│  -------                                                                  │
+│  · User switches UI language toggle, or just speaks Hinglish              │
+│  · "Care Supreme mein PED ka waiting period kya hai?"                     │
+│  · Bot responds in Hinglish with citations preserved                      │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  STEP 9.  Persistent chat across sessions                                 │
+│  -------                                                                  │
+│  · Close tab, come back tomorrow: chat history + profile restored        │
+│  · Sessions persisted to disk on backend; local storage on frontend      │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3B. Technology Flow (parallel)
+
+What's happening under the hood for the same journey.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 1.  Page load                                                       │
+│  -------                                                                  │
+│  · Next.js 14 SSR ships HTML in ~200ms                                    │
+│  · React hydrates; useEffect fetches /api/health, /api/coverage,         │
+│    /api/profile/completeness                                              │
+│  · localStorage rehydrates messages[] + sessionId if returning user      │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 2.  User submits a question                                         │
+│  -------                                                                  │
+│  · Voice path: MediaRecorder blob → POST /api/transcribe → Sarvam        │
+│    Saarika v2.5 STT → text                                                │
+│  · Text path: direct POST /api/chat                                       │
+│  · Payload includes: user_text, session_id, chat_history[],              │
+│    return_audio, tts_language_code, view_context{active_view,            │
+│    active_policy_id, filters}                                             │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 3.  Orchestrator entry — handle_turn()                              │
+│  -------                                                                  │
+│  · classify_intent(user_text) → fact_find / qa / comparison /            │
+│    recommendation                                                         │
+│  · detect_language(user_text) → english / indic                          │
+│  · Indic cascade entry: if indic, Sarvam-M translates → English for      │
+│    reasoning, response will be translated back                            │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 4.  Fact-find OR free-form branch                                   │
+│  -------                                                                  │
+│  · If session.awaiting_question_id and not free_form:                    │
+│      record_answer(session.profile, qid, raw)                            │
+│      next_question(profile) → asks next                                  │
+│      RETURN early                                                         │
+│  · Else: set free_form_session = True, continue to retrieval             │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────���──────────────────────────────────────────────────────────┐
+│  TECH 5.  Profile update extraction (free-form only)                     │
+│  -------                                                                  │
+│  · extract_profile_updates(user_text, session.profile)                    │
+│  · NIM Llama-3.3-70B returns JSON of high-confidence updates             │
+│  · Validation: enum / type / bounds checks; drop on failure              │
+│  · Apply via session.update_profile_field()                              │
+│  · upsert_profile_chunk() re-embeds profile → Chroma                     │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 6.  Retrieval — retrieve(query, session_id)                         │
+│  -------                                                                  │
+│  · BGE-small embeds user_text → 384-d vector                              │
+│  · Chroma cosine search, top_k=5                                          │
+│  · Profile chunk (doc_type='profile') boosted to top of results          │
+│  · Second pass on regulatory chunks if query mentions IRDAI / Section    │
+│  · Returns list[RetrievedChunk(policy_id, page_start, page_end, text,    │
+│    source_url, score)]                                                    │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 7.  Brain selection — pick_brain(intent, language)                  │
+│  -------                                                                  │
+│  · intent ∈ {comparison, recommendation} → DeepSeek-V4-Pro (heavy)        │
+│  · intent ∈ {qa, fact_find} → DeepSeek-V4-Flash (fast)                    │
+│  · All via integrate.api.nvidia.com (single NIM API key)                  │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 8.  System prompt construction                                      │
+│  -------                                                                  │
+│  · build_messages() composes:                                             │
+│    [System: ADVISOR_PROMPT + USER PROFILE block + USER IS LOOKING AT     │
+│       (view_context) block]                                               │
+│    [Assistant/User: last 5 turns of chat_history]                         │
+│    [User: USER QUESTION + RETRIEVED POLICY CLAUSES + reply instructions] │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 9.  Brain LLM call → reply text                                     │
+│  -------                                                                  │
+│  · NIM streaming chat call (V4-Pro or V4-Flash)                           │
+│  · strip_think_tags() removes <think>…</think> chain-of-thought          │
+│  · Capture brain_model_actual for non-circular judge selection           │
+└──────────────────────────────────���───────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 10. Faithfulness gates                                              │
+│  -------                                                                  │
+│  · Gate 1: retrieval floor — top score ≥ 0.30                             │
+│  · Gate 2: citation integrity — every cited policy was retrieved         │
+│  · Gate 3: numeric grounding — every ₹/%/days/months/years in reply      │
+│    appears in retrieved chunks                                            │
+│  · Gate 4: LLM-judge (Llama-4 Maverick, different family from brain)     │
+│  · If all 4 pass → reply ships                                            │
+│  · If any fails (non-Gate-1) → cross-check retry with Maverick           │
+│  · If still fails → safe refusal + log to logs/hallucinations.jsonl      │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 11. Indic cascade (if user spoke Hinglish)                          │
+│  -------                                                                  │
+│  · Sarvam-M translates English reply → Hinglish                           │
+│  · Gate A: regex check that digits/citations/currency preserved          │
+│  · Gate B: Llama-4 Maverick LLM-judge for semantic preservation          │
+│  · Gate C: back-translation cosine ≥ 0.80                                 │
+│  · Any gate fails → fall back to English reply                            │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 12. TTS synthesis (if return_audio=true)                            │
+│  -------                                                                  │
+│  · tts_preprocess() expands acronyms (PED → pre-existing disease) +      │
+│    strips markdown                                                        │
+│  · Sarvam Bulbul v2 synthesizes → base64 WAV                              │
+│  · Bundled into ChatResponse alongside reply_text                         │
+└──────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  TECH 13. Response delivered                                              │
+│  -------                                                                  │
+│  · ChatResponse{reply_text, citations[], audio_base64, brain_used,       │
+│    profile_updates, faithfulness_passed, blocked}                         │
+│  · Frontend renders text → plays audio → updates profileCompleteness     │
+│  · localStorage persists chat history                                    │
+│  · log_turn() writes to logs/turns.jsonl                                  │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Exhaustive tech architecture
+
+### 4.1 System diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  Next.js 14 (Vercel-ready)                                               │
+│  · App Router · Tailwind · shadcn/ui                                     │
+│  · Push-to-talk via MediaRecorder · localStorage persistence            │
+│  · 5 view tabs: chat | marketplace | premium | profile | admin           │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │  HTTPS
+                                  │  /api/chat · /api/transcribe · /api/profile
+                                  │  /api/policies/* · /api/admin/* (IP-gated)
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  FastAPI backend  (HF Spaces / Render)                                   │
+│  ┌──────────────┐    ┌────────────────────┐    ┌────────────────────┐   │
+│  │ STT          │    │ ORCHESTRATOR       │    │ TTS                │   │
+│  │ Sarvam       │───▶│ - intent classify  │───▶│ Sarvam Bulbul v2   │   │
+│  │ Saarika v2.5 │    │ - profile extract  │    │ (acronym pre-exp)  │   │
+│  └──────────────┘    │ - retrieve         │    └────────────────────┘   │
+│                      │ - brain router     │                              │
+│                      │ - 4-gate verifier  │                              │
+│                      │ - cross-check retry│                              │
+│                      │ - Indic cascade    │                              │
+│                      │   (3 drift checks) │                              │
+│                      └─────────┬──────────┘                              │
+│                                │                                         │
+│        ┌───────────────────────┼──────────────────────────┐              │
+│        ▼                       ▼                          ▼              │
+│  ┌──────────────┐    ┌──────────────────┐    ┌──────────────────────┐   │
+│  │ STRUCTURED   │    │ VECTOR STORE     │    │ NIM BRAIN ROUTER     │   │
+│  │ DuckDB       │    │ Chroma 0.5.20    │    │ V4-Pro (heavy)       │   │
+│  │ 48 fields    │    │ BGE-small (384d) │    │ V4-Flash (fast)      │   │
+│  │ per policy   │    │ 800/120 chunk    │    │ Llama-4 Maverick     │   │
+│  └──────────────┘    │ +profile chunk   │    │   (judge + xcheck    │   │
+│                      │   per session    │    │    + Indic gates)    │   │
+│                      └──────────────────┘    │ single NIM key       │   │
+│                                              │ 40 req/min · $0      │   │
+│                                              └──────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  │  (build time only)
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  INGEST  (rag/ingest.py + rag/extract.py + tools/*)                      │
+│  pdfplumber → 800-tok chunks → BGE embed → Chroma                        │
+│  NIM V4-Pro structured extract → 48-field Pydantic schema                │
+│  Self-critique → confidence_pct per field                                │
+└────────────────┬────────────────────────────────────────────────────────┘
+                 │
+                 ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  208 source PDFs in HF Dataset rohitsar567/insurance-bot-data            │
+│  · 190 product PDFs across 19 insurers                                   │
+│  · 18 regulatory PDFs (IRDAI master circulars, Insurance Act, etc.)      │
+│  · Playwright same-origin fetch past Akamai for irdai.gov.in            │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 Components in one line each
+
+| Component | Path | Role |
+|---|---|---|
+| **Frontend** | `frontend/` | Next.js 14 App Router; chat + marketplace + premium + profile + admin tabs |
+| **API gateway** | `backend/main.py` | FastAPI + Pydantic; OpenAPI auto-served; `openapi-typescript` codegens FE types |
+| **Orchestrator** | `backend/orchestrator.py` | Intent classify → profile-extract → retrieve → brain router → 4-gate faithfulness → cross-check retry → Indic cascade |
+| **Faithfulness verifier** | `backend/faithfulness.py` | Retrieval floor + citation integrity + numeric grounding + LLM-judge |
+| **Indic cascade** | `backend/translator.py`, `backend/translation_check.py` | Sarvam-M translates in & out; 3 drift gates |
+| **Profile extractor** | `backend/profile_extractor.py` | Lightweight LLM extracts profile updates from free-form messages |
+| **Profile RAG** | `backend/profile_rag.py` | Profile becomes a single Chroma chunk (`doc_type='profile'`) per session |
+| **Persona** | `backend/persona.py` | System prompt; `build_messages()` injects profile + view_context |
+| **Session state** | `backend/session_state.py` | Per-session profile, fact-find awaiting state, disk-backed JSON |
+| **Retrieval** | `rag/retrieve.py` | Chroma cosine search + profile boost + regulatory second-pass |
+| **Structured extraction** | `rag/extract.py` | NIM V4-Pro JSON extraction over 48-field Pydantic schema |
+| **Scorecard** | `backend/scorecard.py` | Pure Python; 24 of 48 fields → 6 sub-scores → A–F |
+| **Admin** | `backend/admin.py` | LLM health, chain reorder, force-fresh probe; IP-gated |
+| **Eval** | `eval/` | Gold Q&A pipelines + NIM Llama-4 Maverick grader |
+| **Knowledge base** | `kb/` | 224 markdown policy sheets + scorecard + reviews + premiums + audit trail |
+
+### 4.3 Model stack ([ADR-019](docs/60-decisions/ADR-019-nim-single-provider-consolidation.md))
+
+| Role | Model | Provider | Why |
+|---|---|---|---|
+| STT | Saarika v2.5 | Sarvam | Best Indian-accent ASR |
+| TTS | Bulbul v2 (`anushka` voice) | Sarvam | Best Hinglish TTS |
+| Indic translation | Sarvam-M | Sarvam | Best Hindi/Hinglish translation cascade |
+| Heavy brain | DeepSeek-V4-Pro (1.6T / 49B MoE, 1M context) | NIM | Frontier reasoning; beats Opus-4.6 + GPT-5.4 on SimpleQA-Verified |
+| Fast brain | DeepSeek-V4-Flash (284B / 13B MoE, 1M context) | NIM | Lower TTFT for voice; still frontier-tier |
+| Judge / cross-check | Llama-4 Maverick (400B / 17B MoE) | NIM | **Different family from DeepSeek** → non-circular grading |
+| Embeddings | BGE-small-en-v1.5 (384d) | Local | $0; no network |
+| Vector store | Chroma 0.5.20 | Local | Single-file sqlite + HNSW |
+| Structured store | DuckDB 1.1.3 | Local | Single-file; SQL filters for marketplace |
+
+### 4.4 Major design decisions (the short list)
+
+| Decision | Choice | Detail |
+|---|---|---|
+| Scope shape | Vertical slice, one category | [ADR-001](docs/60-decisions/ADR-001-vertical-slice-scope.md) |
+| Category | Health | [ADR-002](docs/60-decisions/ADR-002-health-category-vertical.md) |
+| Corpus origin | Curated, not user-upload | [ADR-003](docs/60-decisions/ADR-003-curated-corpus.md) |
+| Retrieval | Hybrid structured + vector | [ADR-004](docs/60-decisions/ADR-004-hybrid-structured-vector.md) |
+| Frontend stack | Next.js 14 + FastAPI | [ADR-005](docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md) |
+| Pricing | Illustrative, never quote | [ADR-007](docs/60-decisions/ADR-007-illustrative-pricing.md) |
+| Persona | Consultative advisor (IFA) | [ADR-008](docs/60-decisions/ADR-008-consultative-advisor-persona.md) |
+| Embeddings | Local BGE-small | [ADR-011](docs/60-decisions/ADR-011-bge-local-embeddings.md) |
+| LLM provider | NIM single provider | [ADR-019](docs/60-decisions/ADR-019-nim-single-provider-consolidation.md) |
+| Code vs data | Two-repo + HF Dataset | [ADR-020](docs/60-decisions/ADR-020-code-data-split-hf-dataset.md) |
+| View-aware chat | system prompt injection | [ADR-021](docs/60-decisions/ADR-021-view-aware-system-prompt.md) |
+| Profile updates in chat | LLM extractor | [ADR-022](docs/60-decisions/ADR-022-conversational-profile-updates.md) |
+| Admin panel | IP+password gated, in-app tab | [ADR-023](docs/60-decisions/ADR-023-admin-panel-ip-gated.md) |
+| Resilience | Triple-mirror code + data | [ADR-024](docs/60-decisions/ADR-024-triple-mirror-code-and-data.md) |
+
+Every D-NNN in the legacy decisions log is now a stand-alone ADR — see [`docs/60-decisions/README.md`](docs/60-decisions/README.md) for the full 24-entry index.
+
+---
+
+## 5. Data architecture
+
+### 5.1 The corpus (208 documents)
+
+| Type | Count | Source | Notes |
+|---|---|---|---|
+| Product PDFs | 190 | 19 insurers' public websites | Wordings + Brochures + CIS |
+| Regulatory PDFs | 18 | irdai.gov.in, indiacode.nic.in, others | Playwright rescue past Akamai |
+| Structured extractions (JSON) | 285 | NIM V4-Pro extraction | 48-field Pydantic schema |
+| Vector chunks (Chroma) | ~12,000 | BGE-small @ 800/120 | One sqlite + HNSW binaries |
+| Policy markdown sheets | 224 | Generated from extractions | One per policy_id in `kb/policies/` |
+
+19 insurers: Star Health, HDFC ERGO, Niva Bupa, Care Health, ICICI Lombard, Bajaj Allianz, New India Assurance, Aditya Birla, Tata AIG, ManipalCigna, SBI General, Acko, IFFCO Tokio, Cholamandalam MS, Go Digit, Reliance General, Royal Sundaram, Oriental Insurance, National Insurance.
+
+### 5.2 Ingestion pipeline
+
+```
+PDF (rag/corpus/<insurer>/<policy>__<doctype>.pdf)
+  │
+  ▼
+rag/extract.py    →    rag/extracted/<policy_id>.json    (48-field structured)
+  │                                                       (NIM V4-Pro with Pydantic schema)
+  │
+  ▼
+rag/ingest.py     →    rag/vectors/chroma.sqlite3        (text chunks + embeddings)
+  │                    + HNSW binary files in vectors/   (800-token chunks, 120 overlap)
+  │
+  ▼
+data/policy_facts/<policy_id>.json                       (hand-curated facts for marketplace UI)
+data/premiums/illustrative_premiums.json                  (anchor table for premium calculator)
+data/reviews/<insurer-slug>.json                          (IRDAI complaints/10K + sentiment roll-ups)
+  │
+  ▼
+kb/policies/<policy_id>.md                               (markdown writeup; regen via rag/build_kb.py)
+```
+
+Full per-stage detail: [`docs/20-data-pipeline/ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md).
+
+### 5.3 Storage topology
+
+| Storage | What lives there | Quota |
+|---|---|---|
+| HF Space repo (origin) | Code only (`backend/`, `frontend/`, `rag/*.py`, `eval/`, `kb/`, `data/`, configs) | 1 GB free tier |
+| HF Dataset | Heavy data: `rag/corpus/`, `rag/vectors/`, `rag/extracted/` | 50 GB free tier (we use ~500 MB) |
+| GitHub code repo | Mirror of HF Space | Standard GitHub |
+| GitHub data repo (LFS) | Mirror of HF Dataset | 1 GB LFS + 1 GB/mo bandwidth |
+| Local Mac | Working tree + `rag/_hf_dataset_backup/` for offline recovery | Filesystem |
+
+Runtime path: Docker container running on HF Space `snapshot_download`s the dataset at build time → serves everything from local container disk → end users never hit GitHub or the dataset at request time.
+
+---
+
+## 6. Quality & safety
+
+### 6.1 The four faithfulness gates ([`backend/faithfulness.py`](backend/faithfulness.py))
+
+Every reply, every turn:
+
+| Gate | Function | Blocks if |
+|---|---|---|
+| 1. Retrieval floor | `_gate_retrieval_floor` | Top retrieval score < 0.30 — nothing to ground in |
+| 2. Citation integrity | `_gate_citation_integrity` | Reply cites a policy_name not in retrieved chunks |
+| 3. Numeric grounding (regex) | `_gate_numeric_grounding` | Any ₹/%/days/months/years in reply doesn't appear in chunks |
+| 4. LLM-judge | `_gate_llm_judge` | NIM Llama-4 Maverick (different family from brain) flags unsupported claim |
+
+If any gate (other than Gate 1) fails, the **cross-check retry** re-runs the same prompt on Llama-4 Maverick. If that passes its gates, the rescued reply ships with `crosscheck-rescued-by-maverick` brain tag. Otherwise → safe refusal + log to `logs/hallucinations.jsonl`.
+
+### 6.2 Indic drift gates ([`backend/translation_check.py`](backend/translation_check.py))
+
+When the user speaks Hinglish:
+
+| Gate | Method |
+|---|---|
+| A — Regex anchors | Every digit / currency / citation in the English reply must appear in the Indic reply |
+| B — LLM-judge | NIM Llama-4 Maverick scores semantic faithfulness across languages |
+| C — Back-translation cosine | Sarvam back-translates Hinglish → English; cosine vs original ≥ 0.80 |
 
-1. [`docs/01-requirements.md`](docs/01-requirements.md) — product vision, personas, success criteria, non-goals
-2. [`docs/02-architecture.md`](docs/02-architecture.md) — stack picks, schema, system design *(in progress)*
-3. [`docs/03-eval-plan.md`](docs/03-eval-plan.md) — gold Q&A pairs, automated grader, accuracy targets *(in progress)*
-4. [`docs/04-failure-modes.md`](docs/04-failure-modes.md) — known failure modes + mitigations *(in progress)*
-5. [`docs/05-needs-analysis-flow.md`](docs/05-needs-analysis-flow.md) — fact-find question graph *(in progress)*
-6. [`docs/decisions.md`](docs/decisions.md) — every meaningful decision logged with alternatives + reasoning
-7. [`docs/ROADMAP.md`](docs/ROADMAP.md) — how this scales from v1 vertical slice to full platform
+Any gate fails → revert to English reply (correct facts even if not preferred language).
 
-## Quick start
+### 6.3 Eval methodology
+
+Gold Q&A in three pipelines:
+
+- **A — Auto-templated:** 15 templates × ~80 policies = 1,100 candidates, ~300 committed.
+- **B — LLM-drafted nuanced:** V4-Pro drafts 5 buyer-style multi-clause questions per top policy.
+- **C — Adversarial:** 30-40 hand-written out-of-corpus / out-of-policy-type / Hinglish / multi-policy.
+
+Grader: NIM Llama-4 Maverick (non-circular — different family from the DeepSeek brain). Source: [`eval/generate_gold.py`](eval/generate_gold.py), [`eval/run.py`](eval/run.py).
+
+Honest current numbers (2026-05-12 run on 25 questions):
+
+| Metric | Value | Comment |
+|---|---|---|
+| Factual accuracy | 40.0% | Two structural causes — see [`SUBMISSION.md`](SUBMISSION.md) §4.3 |
+| Citation accuracy | 50.0% | Same |
+| Refusal precision | 44.4% | Same |
+| Blocked by faithfulness | 12 / 25 | Gates working; aggressively biased toward refusal |
+
+The headline number reflects an aggressive gate posture (refuse > mis-cite) — the safe failure mode in BFSI. v1.1 work: soften Gate 3 regex; null-skip Pipeline A on missing source fields.
+
+---
+
+## 7. Document ecosystem guide
+
+The repo's documentation lives in `docs/`, organised into 8 numbered buckets. Numeric prefixes sort buckets in reading order; files inside each bucket use `kebab-case` for URL safety and grep-friendliness.
+
+```
+docs/
+├── 00-overview/              ← "what is this and why does it exist"
+├── 10-architecture/          ← "how it works" (deep dives)
+├── 20-data-pipeline/         ← "where the knowledge comes from"
+├── 30-engineering/           ← "how the code is laid out"
+├── 40-evaluation/            ← "how we measured success"
+├── 50-operations/            ← "how to run / maintain / debug"
+├── 60-decisions/             ← Architecture Decision Records (ADRs 001-024)
+└── 70-reference/             ← Schemas, glossary, indexes
+```
+
+### 7.1 Per-bucket guide
+
+| Bucket | What's there now | What to read for what |
+|---|---|---|
+| `00-overview/` | [`problem-statement.md`](docs/00-overview/problem-statement.md), [`roadmap.md`](docs/00-overview/roadmap.md) | Start here for product context, requirements, success criteria, v2 plan |
+| `10-architecture/` | [`system-overview.md`](docs/10-architecture/system-overview.md), [`stack-rationale.md`](docs/10-architecture/stack-rationale.md), [`safety-architecture.md`](docs/10-architecture/safety-architecture.md), [`scoring-methodology.md`](docs/10-architecture/scoring-methodology.md), [`scoring-knowledge-graph.md`](docs/10-architecture/scoring-knowledge-graph.md), [`scoring-tie-breaker-rubric.md`](docs/10-architecture/scoring-tie-breaker-rubric.md) | How the system is built; the why behind each stack choice; how scoring works |
+| `20-data-pipeline/` | [`ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md), [`information-source-map.md`](docs/20-data-pipeline/information-source-map.md) | How PDFs become chunks; where every source URL lives + audit status |
+| `30-engineering/` | [`needs-analysis-flow.md`](docs/30-engineering/needs-analysis-flow.md), [`discovery-script.md`](docs/30-engineering/discovery-script.md) | How the fact-find loop works; discovery script for new contributors |
+| `40-evaluation/` | [`eval-methodology.md`](docs/40-evaluation/eval-methodology.md) | Gold-Q&A design, grader choice, results interpretation |
+| `50-operations/` | (operational runbooks — to be filled) | How to run, deploy, debug |
+| `60-decisions/` | 24 ADRs + [`README.md`](docs/60-decisions/README.md) index + `legacy-decisions-monolith.md` archive | The full decision history with alternatives and supersession tracking |
+| `70-reference/` | (schemas + glossary — to be filled) | BFSI terms, insurer slug map, citation grammar |
+
+### 7.2 Root-level documents
+
+| File | Purpose |
+|---|---|
+| `README.md` (this file) | Master entry point + executive bible |
+| `SUBMISSION.md` | Formal Sarvam takehome writeup; the polished narrative for reviewers |
+| `ARCHITECTURE.md` | One-page diagram + index into `docs/10-architecture/` |
+| `QUICKSTART.md` | Run-locally-in-5-minutes guide (see §8 below) |
+| `Dockerfile` | Production build — pulls dataset at build time, serves Next.js + FastAPI |
+| `entrypoint.sh` | Docker entrypoint — boots both processes |
+| `requirements.txt` | Python deps (pinned) |
+| `render.yaml` | Legacy Render config (HF Space is current production) |
+
+### 7.3 Navigation shortcuts
+
+- **Reviewer with 5 minutes:** read [SUBMISSION.md](SUBMISSION.md) §1, §3, §6 (limits).
+- **Reviewer with 20 minutes:** read this README end-to-end.
+- **Engineer joining the project:** read [`docs/00-overview/problem-statement.md`](docs/00-overview/problem-statement.md) → [`docs/10-architecture/system-overview.md`](docs/10-architecture/system-overview.md) → [`docs/60-decisions/README.md`](docs/60-decisions/README.md) → trace `backend/orchestrator.py`.
+- **Compliance auditor:** read [`docs/10-architecture/safety-architecture.md`](docs/10-architecture/safety-architecture.md) → `logs/hallucinations.jsonl` → [`kb/AUDIT_TRAIL.md`](kb/AUDIT_TRAIL.md).
+- **Replicating the data pipeline:** read [`docs/20-data-pipeline/ingestion-policy.md`](docs/20-data-pipeline/ingestion-policy.md) → trace `rag/extract.py` + `rag/ingest.py`.
+
+---
+
+## 8. Quick start & local development
+
+### 8.1 Prerequisites
+
+- macOS or Linux
+- Python 3.11+
+- Node.js 20+
+- ~5 GB free disk for venv + node_modules + dataset
+
+### 8.2 Clone & install
 
 ```bash
+# Code
 git clone https://github.com/rohitsar567/insurance-sales-bot.git
 cd insurance-sales-bot
-python -m venv .venv && source .venv/bin/activate
-pip install -r requirements.txt
-cp .env.example .env  # then fill in SARVAM_API_KEY
-streamlit run streamlit_app.py
+
+# Data (for local-only runs — Docker pulls automatically)
+git clone https://github.com/rohitsar567/insurance-sales-bot-data.git rag/_hf_dataset_backup
+# OR via huggingface_hub:
+# python -c "from huggingface_hub import snapshot_download; \
+#   snapshot_download(repo_id='rohitsar567/insurance-bot-data', repo_type='dataset', \
+#                     local_dir='rag/_hf_dataset_backup')"
+
+# Move data into place for the bot
+cp -R rag/_hf_dataset_backup/rag/* rag/   # corpus/, extracted/, vectors/
+```
+
+### 8.3 Configure secrets
+
+```bash
+cp .env.example .env
+# Edit .env and fill in the 8 keys (see docs/60-decisions/ADR-010-secret-handling.md):
+#   SARVAM_API_KEY, VOYAGE_API_KEY, NVIDIA_NIM_API_KEY, HF_TOKEN,
+#   ADMIN_PASSWORD, ADMIN_IP_ALLOWLIST, GROQ_API_KEY, OPENROUTER_API_KEY
+chmod 600 .env
 ```
 
-## Architecture at a glance
+### 8.4 Run backend
+
+```bash
+# Recommended: uv-managed venv
+uv venv ~/.cache/uv-venvs/insurance-sales-bot --python 3.11
+ln -s ~/.cache/uv-venvs/insurance-sales-bot .venv
+uv pip install -r requirements.txt
 
+uvicorn backend.main:app --reload --port 7860
 ```
-User voice → Sarvam Saaras (STT) → Orchestrator → Sarvam-M (LLM)
-                                          ↓
-                                  Hybrid retrieval:
-                                  ├─ Structured (DuckDB) — filters, comparison
-                                  └─ Unstructured (Chroma) — chunked PDFs, RAG
-                                          ↓
-                                  Cited response → Sarvam Bulbul (TTS) → User
+
+### 8.5 Run frontend
+
+```bash
+cd frontend
+npm install
+npm run dev   # http://localhost:3000
 ```
 
-## What's in scope for v1 (the vertical slice)
+### 8.6 Verify
 
-- 19 insurers × all their health policies (190 insurer PDFs + 18 regulatory)
-- 40–50 structured fields per policy (premium, sum insured, waiting periods, PED, sub-limits, network, claim ratio, geography, etc.)
-- Voice advisor with Hindi/English code-switch
-- Adaptive needs analysis
-- Granular filter + side-by-side comparison
-- Illustrative pricing bands
+- Frontend at `localhost:3000` should show the chat UI.
+- `localhost:7860/api/health` should return `{"status":"ok", "providers_ok": {"sarvam": true, "nvidia_nim": true}}`.
+- `localhost:7860/api/coverage` should return 255 policies indexed.
 
-## What's out of scope (v2 roadmap)
+---
 
-See [`docs/01-requirements.md` §7](docs/01-requirements.md).
+## 9. Deployment & storage topology
 
-## Built with
+### 9.1 Triple-mirror layout
 
-- **STT**: Sarvam Saaras
-- **TTS**: Sarvam Bulbul
-- **LLM**: Sarvam-M
-- **Vector DB**: Chroma
-- **Structured DB**: DuckDB
-- **UI**: Streamlit
+| Layer | Code | Data |
+|---|---|---|
+| **HuggingFace** | Space `rohitsar567/InsuranceBot` (origin) | Dataset `rohitsar567/insurance-bot-data` |
+| **GitHub** | Repo `rohitsar567/insurance-sales-bot` | Repo `rohitsar567/insurance-sales-bot-data` (Git LFS) |
+| **Local Mac** | `~/Developer/Insurance Sales Bot/` working tree | `~/Developer/Insurance Sales Bot/rag/_hf_dataset_backup/` |
 
-Each pick is justified in [`docs/decisions.md`](docs/decisions.md).
+### 9.2 Push fan-out
+
+```bash
+# After a commit:
+git push origin main      # → HF Space (auto-deploys via Docker rebuild)
+git push github main      # → GitHub mirror
+
+# For data updates (rare):
+cd rag/_hf_dataset_backup  # or wherever the data lives
+git push origin main      # → HF Dataset
+git push github main      # → GitHub LFS data repo
+```
+
+Verification: `git rev-list --count main...origin/main` and `…main...github/main` should both equal 0.
+
+### 9.3 Production runtime path
+
+```
+End user
+  │  HTTPS
+  ▼
+rohitsar567-insurancebot.hf.space   (HF Space Docker container)
+  │
+  │  Container has data baked in (snapshot_download at build time)
+  ▼
+FastAPI + Next.js serve from local container disk; calls go out to:
+  - NIM (integrate.api.nvidia.com) for brain + judge + extractor
+  - Sarvam (api.sarvam.ai) for STT + TTS + Indic translation
+```
+
+End users **never** touch GitHub. The data repo is for portfolio mirroring + disaster recovery — not a runtime dependency.
+
+### 9.4 Admin operations
+
+| Operation | Command / surface |
+|---|---|
+| Rotate any API key | Edit local `.env` → `python tools/set_hf_secrets.py` → Space auto-restarts |
+| Add admin IP | Edit `ADMIN_IP_ALLOWLIST` in `.env` (comma-separated) → `set_hf_secrets.py` |
+| Reorder LLM chain | In-app **Admin · Access panel** tab → "Force fresh probe" → drag-reorder |
+| Force fresh model probe | Same tab → "Force fresh probe (slow)" |
+| Disaster recovery (HF Dataset lost) | Re-upload from local `rag/_hf_dataset_backup/` via `huggingface_hub.HfApi.upload_folder` |
+| Cold start | First request after ~15 min idle takes ~50s; subsequent are fast |
+
+---
+
+## 10. Rebuild from scratch
+
+This section is written so a fresh **Claude Code** session pointed at an empty directory could rebuild the entire project end-to-end. The goal is to make the project reproducible from this document plus the linked dependencies.
+
+### 10.1 Required external accounts
+
+1. **Sarvam** — STT, TTS, Indic translation. Get API key at dashboard.sarvam.ai.
+2. **NVIDIA NIM** — brain + judge + extractor. Get `nvapi-...` key at build.nvidia.com.
+3. **HuggingFace** — Space + Dataset hosting. Get write token at huggingface.co/settings/tokens.
+4. **GitHub** — mirror code + data. Personal Access Token with `repo` scope.
+5. **Voyage / Groq / OpenRouter** — optional fallback (kept for flexibility).
+
+### 10.2 Build sequence
+
+1. **Corpus acquisition** — use `tools/` agent crawl + Playwright fallback (see [ADR-017](docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md)) to fetch 19 insurers' PDFs + 18 regulatory PDFs into `rag/corpus/`.
+
+2. **Structured extraction** — `rag/extract.py` runs NIM V4-Pro over each PDF with the 48-field Pydantic schema. Output to `rag/extracted/<policy_id>.json`.
+
+3. **Embedding + indexing** — `rag/ingest.py` chunks each PDF at 800/120, embeds with BGE-small-en-v1.5, writes to `rag/vectors/chroma.sqlite3` + HNSW binaries.
+
+4. **Data publish** — push `rag/corpus/`, `rag/extracted/`, `rag/vectors/` to HF Dataset `rohitsar567/insurance-bot-data`.
+
+5. **Knowledge base regeneration** — `python -m rag.build_kb` regenerates 224 markdown sheets in `kb/policies/` from extracted JSONs.
+
+6. **Backend** — implement FastAPI app with the endpoints listed in §4.2. Key files: `backend/main.py`, `backend/orchestrator.py`, `backend/faithfulness.py`, `backend/persona.py`, `backend/translator.py`, `backend/translation_check.py`, `backend/profile_extractor.py`, `backend/profile_rag.py`, `backend/session_state.py`, `backend/scorecard.py`, `backend/admin.py`, `backend/providers/*`.
+
+7. **Frontend** — Next.js 14 App Router. Tailwind + shadcn/ui. Key file: `frontend/src/app/page.tsx` (orchestrates all views: chat, marketplace, premium, profile, admin). Voice via MediaRecorder. Persistent state via localStorage.
+
+8. **Eval harness** — `eval/generate_gold.py` builds the gold Q&A. `eval/run.py` grades using NIM Llama-4 Maverick. Output to `eval/results.md`.
+
+9. **Deploy** — Dockerfile bundles backend + frontend (Next.js standalone) into one image. `snapshot_download` pulls data at build time. Push to HF Space — auto-deploys.
+
+10. **Mirror to GitHub** — `git remote add github https://github.com/rohitsar567/insurance-sales-bot.git` + push. Same for data repo with Git LFS.
+
+### 10.3 Critical files to seed first (priority order)
+
+A new Claude Code session should ingest these to bootstrap understanding:
+
+1. **This README** — entire project context.
+2. **[`SUBMISSION.md`](SUBMISSION.md)** — formal narrative + eval results.
+3. **[`docs/60-decisions/`](docs/60-decisions/)** — 24 ADRs covering every meaningful decision.
+4. **[`backend/orchestrator.py`](backend/orchestrator.py)** — the single file that defines a turn.
+5. **[`backend/faithfulness.py`](backend/faithfulness.py)** — the 4-gate verifier.
+6. **[`backend/persona.py`](backend/persona.py)** — the system prompt + message builder.
+7. **[`rag/retrieve.py`](rag/retrieve.py)** — retrieval logic with profile boost.
+8. **[`frontend/src/app/page.tsx`](frontend/src/app/page.tsx)** — full UI orchestration.
+
+### 10.4 Hidden gotchas a rebuilder will hit
+
+| Gotcha | Where it bites | Fix |
+|---|---|---|
+| IRDAI URLs return Akamai bot-challenge HTML | Initial corpus crawl | Playwright same-origin fetch (ADR-017) |
+| Sarvam-M output cap 2048 tokens truncates JSON | Extraction phase | Use NIM V4-Pro instead (ADR-019) |
+| Voyage 3 RPM free-tier blocks 208-PDF ingest | Embedding phase | Switch to local BGE-small (ADR-011) |
+| Multiple LLM providers' free-tier limits collide on grader | Eval phase | Consolidate to NIM (ADR-019) |
+| HF Space 1 GB cap rejects vector DB | Deploy phase | Split data to HF Dataset (ADR-020) |
+| Chroma sqlite3 (157 MB) exceeds GitHub 100 MB per-file limit | GitHub mirror | Use Git LFS for the data repo (ADR-024) |
+| iCloud-synced `~/Documents/` causes node_modules upload churn | Local dev | Move project to `~/Developer/` (not in iCloud) |
+| Apple Python 3.9 lacks `int | None` syntax | LaunchAgent scripts | Add `from __future__ import annotations` |
+| Admin endpoints return 404 (not 401) for unauthorized callers | Admin panel | Intentional — hides existence; pair IP allowlist with X-Admin-Password header |
+
+---
 
-## Deploying changes
+## Footer
 
-All extraction, embedding, and Chroma writes for the curated corpus run on the developer's Mac. The deployed HF Space serves pre-built indexes and does not auto-ingest (the one exception is user-uploaded PDFs, which embed on-demand into an isolated `user_uploads_quarantine` collection). Full rationale and the per-stage where-it-runs table: [`docs/ingestion_policy.md`](docs/ingestion_policy.md).
+**Authored 2026-05-13. Last updated 2026-05-14.**
 
-After any corpus change, run these four commands sequentially from the project root with the local `.venv` active:
+Live demo: https://rohitsar567-insurancebot.hf.space  
+Code: https://github.com/rohitsar567/insurance-sales-bot  
+Data: https://github.com/rohitsar567/insurance-sales-bot-data  
+Contact: rohitsar567@gmail.com
 
-- [ ] `.venv/bin/python -m rag.ingest` — rebuild the Chroma index locally
-- [ ] `.venv/bin/python tools/upload_vectors_to_dataset.py` — push `rag/vectors/` to the HF dataset
-- [ ] `.venv/bin/python tools/upload_extracted_to_dataset.py` — push `rag/extracted/` (only if structured JSONs changed)
-- [ ] `.venv/bin/python tools/upload_to_hf.py` — push code to the Space (triggers a Docker rebuild that pulls the dataset)
+If you're reviewing this for Sarvam: thank you for your time. Every architectural choice is in [`docs/60-decisions/`](docs/60-decisions/) with alternatives and reasoning. Every refusal in the demo is logged in `logs/hallucinations.jsonl` with the failing gate. The project is structured so a new engineer could ship v1.1 by Friday.

docs/60-decisions/ADR-001-vertical-slice-scope.md

@@ -0,0 +1,33 @@
+# ADR-001: Vertical slice scope, not full platform
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+The Sarvam takehome assignment had a ~24-hour build window with explainability as an explicit grading criterion. Three scope shapes were on the table:
+
+1. Single-document RAG-voice bot over one policy.
+2. Vertical slice — full architecture for one category (Health), built so category expansion is config + data, not code.
+3. Full platform — 300+ policies across all insurance categories.
+
+## Decision
+
+Build the vertical slice. One category (Health) — but every architectural surface a reviewer cares about is real: hybrid retrieval, schema, voice cascade, citations, evaluation, audit trail, refusal behaviour, scorecard methodology, deployment.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Single-document RAG | Under-signals product vision; reviewer can't see how the system would scale. |
+| Full platform | Over-scopes within 24h; ships rough; quality bar suffers across the board. |
+
+## Consequences
+
+**Positive:** Demonstrates senior-engineer scoping discipline. Every part of the bot a BFSI buyer would audit (provenance, refusal, eval rigor) is real, not stubbed.
+
+**Negative:** Life, Motor, and other categories are not covered. The seven "c-readiness commitments" in `docs/10-architecture/system-overview.md` §7 become real v2 work.
+
+## Revisit at scale (v2)
+
+Category expansion plan in `docs/00-overview/roadmap.md`. Each new category requires: (1) corpus acquisition, (2) per-category schema extension, (3) eval gold set, (4) scorecard sub-score weights. No core code changes.

docs/60-decisions/ADR-002-health-category-vertical.md

@@ -0,0 +1,36 @@
+# ADR-002: Health as the v1 vertical category
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+Given the vertical-slice scope (ADR-001), one insurance category had to be chosen. Candidates: Health, Life, Motor.
+
+## Decision
+
+**Health insurance.**
+
+## Alternatives considered
+
+| Category | Why not for v1 |
+|---|---|
+| Life insurance | Harder emotional sale; numerical comparison less clean; smaller buyer-controlled-decision share (term life is the only directly comparable product). |
+| Motor insurance | Price-commoditised; lower BFSI margin; less compelling demo (less depth to compare). |
+
+## Why Health
+
+1. **Richest structured-attribute surface** — waiting periods, PED handling, sub-limits, network hospitals, claim ratio, geographic spread, restoration benefits, room rent caps, AYUSH coverage, OPD riders. Enough fields to make cross-policy comparison non-trivial.
+2. **Broadest user relevance** — every Indian adult has or considers health insurance.
+3. **Cleanest public corpus** — top 19 insurers all publish policy wordings, brochures, and CIS documents on their public websites.
+4. **Regulator-rich** — IRDAI master circulars define standard exclusions, free-look periods, portability rules. Gives the bot a natural "regulatory overlay" layer (see ADR-017).
+
+## Consequences
+
+**Positive:** Maximum surface area for demonstrating the architecture in v1.
+
+**Negative:** Life and Motor users see "this only covers Health."
+
+## Revisit at scale
+
+v2 adds Life (term + ULIP + endowment) and Motor (private car + two-wheeler). The 48-field Health schema generalises with ~70% reuse — most additions are category-specific waiting/exclusion fields.

docs/60-decisions/ADR-003-curated-corpus.md

@@ -0,0 +1,40 @@
+# ADR-003: Curated corpus over user-uploaded PDFs
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+A health-insurance bot needs PDF text to ground its answers. The PDFs can come from either:
+
+1. **Curated** — we acquire a corpus once, version it, embed it offline.
+2. **User-uploaded** — every user uploads their own policy doc; the bot extracts on the fly.
+
+## Decision
+
+**Curated corpus** of 190 policy PDFs (19 insurers) + 18 regulatory PDFs. User-uploads are accepted but routed to an isolated `user_uploads_quarantine` Chroma collection so they never pollute the canonical retrieval.
+
+## Alternatives considered
+
+| Approach | Why rejected for v1 |
+|---|---|
+| Pure user-upload | Highest input variance (bad scans, password-protected PDFs, partial documents). No cross-policy comparison possible — the bot only knows what the user just uploaded. |
+| Hybrid with shared collection | User uploads polluting shared retrieval would let one bad upload poison answers for every other user. |
+
+## Consequences
+
+**Positive:**
+
+- Removes the largest source of input variance (bad uploads).
+- Enables cross-policy comparison and recommendation queries — the core differentiator.
+- Positions the corpus as a product moat vs. generic "RAG over anything" bots.
+- Provenance is verifiable: every PDF traces to a public insurer URL with HEAD-verified status.
+
+**Negative:**
+
+- Corpus acquisition is the longest-pole task in the build (acquired via the `tools/` agent crawl + Playwright rescue — see ADR-017).
+- Corpus freshness depends on a manual refresh cadence.
+
+## Revisit at scale
+
+Same approach, larger corpus. Add scheduled monthly refresh job that re-fetches every URL via Playwright and re-embeds any changed PDF. User-upload quarantine collection remains isolated.

docs/60-decisions/ADR-004-hybrid-structured-vector.md

@@ -0,0 +1,52 @@
+# ADR-004: Hybrid structured + vector retrieval
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+A health-insurance assistant has two qualitatively different query classes:
+
+1. **Filter / comparison / recommendation** — "Show me policies with restoration benefit AND PED waiting < 24 months AND room rent ≥ ₹10k." These need structured fields, not retrieval.
+2. **Free-form Q&A with citations** — "What does Care Supreme say about cataract waiting?" These need unstructured text with clause-level citation.
+
+A single retrieval mechanism is wrong for both.
+
+## Decision
+
+**Hybrid architecture:**
+
+| Concern | Store | Used for |
+|---|---|---|
+| Structured fields per policy (48 fields) | **DuckDB** (`rag/policies.duckdb`) | Marketplace filters, scorecard inputs, side-by-side comparison |
+| Free-form text chunks with provenance | **Chroma** (`rag/vectors/chroma.sqlite3`) | Citation-bearing Q&A, regulatory grounding |
+
+The two stores are linked by canonical `policy_id` (e.g., `care-health__care-supreme__wordings`).
+
+## Alternatives considered
+
+| Approach | Why rejected |
+|---|---|
+| Pure RAG | Filter queries become 50-line LLM prompts that hallucinate; comparison can't scale. |
+| Pure structured DB | No clause-level citation; can't answer "what does the policy say about X" for fields not in schema. |
+| Single store with structured-as-metadata | Possible but couples schema evolution to vector index rebuild. |
+
+## Consequences
+
+**Positive:**
+
+- Each query class hits the right store.
+- Schema evolution doesn't trigger expensive re-embedding.
+- DuckDB is single-file, embeddable; no infra burden.
+
+**Negative:**
+
+- Two stores to keep in sync at ingest time (`rag/ingest.py`).
+- Cross-cutting queries ("policies where wording mentions 'restoration' AND structured.network_hospital_count > 10000") require small bridge code.
+
+## Revisit at scale
+
+| Pressure | Migration path |
+|---|---|
+| Multi-tenant | DuckDB → Postgres |
+| 10× corpus | Chroma → Pinecone or Qdrant (interface stays the same; see `rag/retrieve.py`) |

docs/60-decisions/ADR-005-nextjs-fastapi-frontend.md

@@ -0,0 +1,45 @@
+# ADR-005: Next.js 14 + FastAPI (revised from Streamlit)
+
+**Status:** Locked (revised mid-build)
+**Date:** 2026-05-13 (revision)
+
+## Context
+
+The original v1 plan locked Streamlit for the UI (D-005 original). Mid-build, the constraint was unlocked ("use whatever is best"). A re-evaluation surfaced that Streamlit's "this looks like a prototype" perception would undercut the BFSI-deployable-product signal the project is trying to send to reviewers.
+
+## Decision
+
+**Next.js 14 (App Router) frontend + FastAPI backend.** Vercel for FE auto-deploy; HF Space for BE (`origin`) with full mirroring to GitHub (see ADR-024).
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Streamlit (original) | Fast to demo, but signals "prototype" to a BFSI reviewer. Audio streaming and multi-user state awkward. |
+| Gradio | Same prototype perception; ML-research vibe. |
+| Chainlit | Specialised for chat-only UIs; comparison/marketplace panels harder. |
+| Reflex (formerly Pynecone) | Python-only; less ecosystem; smaller community. |
+
+## Consequences
+
+**Positive:**
+
+- Production-pattern stack matches what a deploying customer (bank, insurer) would expect.
+- Server-side rendering via Next.js → fast initial paint.
+- Tailwind + shadcn/ui (ADR-013) gives polished design without bespoke CSS.
+- FastAPI ships OpenAPI for free → `openapi-typescript` codegen (ADR-015) keeps frontend types in sync with backend.
+
+**Negative:**
+
+- Extra ~2-3 hours of scaffolding versus Streamlit.
+- FE/BE auth + CORS + dual deploy add complexity.
+
+**Mitigations:**
+
+- `openapi-typescript` codegen so types update automatically.
+- Single CORS allowlist in `backend/main.py` (currently `*` for v1, narrowed for v2).
+- Vercel + HF Space both auto-deploy from the same GitHub repo on push.
+
+## Revisit at scale
+
+Same stack. Standard production pattern for AI products in 2026.

docs/60-decisions/ADR-006-sarvam-first-stack.md

@@ -0,0 +1,42 @@
+# ADR-006: Sarvam-first defaults for STT/TTS/LLM
+
+**Status:** Partially superseded by [ADR-019](ADR-019-nim-single-provider-consolidation.md)
+**Date:** 2026-05-13
+
+## Context
+
+This is a Sarvam AI take-home assignment. Silent defaults to non-Sarvam providers would screen out, regardless of technical merit.
+
+## Decision
+
+**Sarvam-first benchmarking** for every voice and reasoning component:
+
+- STT: Sarvam Saarika v2.5 vs. Whisper / Deepgram
+- TTS: Sarvam Bulbul v2 vs. ElevenLabs / OpenAI TTS
+- LLM: Sarvam-M vs. GPT-4o / Claude
+
+Components live behind thin interfaces (`backend/providers/base.py`) so swapping any one is a config flag, not a refactor.
+
+## Outcome — what's still Sarvam after ADR-019
+
+| Layer | v1 (this ADR) | After ADR-019 |
+|---|---|---|
+| STT | Sarvam Saarika v2.5 | **Stays Sarvam** — best Indian-accent recognition |
+| TTS | Sarvam Bulbul v2 | **Stays Sarvam** — best Hinglish TTS |
+| Indic translation | Sarvam-M | **Stays Sarvam** — best Hinglish/Hindi translation |
+| Reasoning brain | Sarvam-M | **Moved to NIM DeepSeek-V4-Pro / V4-Flash** — Sarvam-M's 2048 output cap + `<think>` tokens caused mid-JSON truncation. See ADR-019. |
+| Judge | Sarvam-M self-judge | **Moved to NIM Llama-4 Maverick** — different family from the brain for non-circular evaluation. |
+
+## Why partial supersession is the honest narrative
+
+ADR-019's framing in the SUBMISSION doc: *"Sarvam isn't trying to win a benchmark it doesn't need to win."* The voice + Indic pieces are where Sarvam is uniquely strong and closed-source frontier cannot match. The reasoning role is a different problem; MIT-licensed open-weights frontier (DeepSeek-V4-Pro) is a strictly better fit on a free tier with no rate cap.
+
+## Consequences
+
+**Positive:** Project leads with Sarvam exactly where Sarvam beats the world.
+
+**Negative:** Slight increased complexity — three providers instead of one (Sarvam + NIM + local BGE embeddings).
+
+## Revisit at scale
+
+When Sarvam ships a longer-context reasoning model (current cap 2048 is the blocker), benchmark it against DeepSeek-V4-Pro on the same gold set and consider unifying.

docs/60-decisions/ADR-007-illustrative-pricing.md

@@ -0,0 +1,48 @@
+# ADR-007: Illustrative pricing, not real-time quotes
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+Buyers expect to see premium estimates. Indian insurers hide real pricing behind a phone-callback flow; there is no public quote API. Three paths exist:
+
+1. Illustrative band, anchored to public rate cards, with explicit disclaimer.
+2. Scrape comparison portals (PolicyBazaar etc.) at query time.
+3. Build an actuarial model from first principles.
+
+## Decision
+
+**Path 1: illustrative band with disclaimer.** Path 2 used only for top-5 ground-truth validation of the anchor cells.
+
+## Alternatives considered
+
+| Path | Why rejected as primary |
+|---|---|
+| (2) Live scrape | Legally gray (ToS), brittle to UI changes, slow per-query, doesn't capture insurer-callback dynamics. |
+| (3) Actuarial model | Out of scope; data inputs unavailable; v1 build window doesn't permit it. |
+
+## Implementation
+
+- `data/premiums/illustrative_premiums.json` holds the anchor table.
+- Anchor cells sourced from public PolicyBazaar quote pages and insurer rate cards (provenance in `kb/premiums/INDEX.md`).
+- Missing `(insurer, policy, age, SI, family-composition)` cells are extrapolated using scaling factors derived from the visible anchor points + standard IRDAI age-bandings.
+- **Every premium reply from the bot carries an explicit illustrative disclaimer.**
+- Premium calculator UI panel (frontend) shows the same disclaimer prominently.
+
+## Consequences
+
+**Positive:**
+
+- Honest about precision — no implied false certainty.
+- Reinforces the "advisor not broker" positioning.
+- Removes legal risk of pretending to broker quotes.
+
+**Negative:**
+
+- Users get an estimate band, not a specific number.
+- Conversion to actual purchase still requires insurer/aggregator handoff.
+
+## Revisit at scale
+
+v2 path: B2B partnership with an aggregator (PolicyBazaar, Ditto, InsuranceDekho) or direct insurer APIs to get real quotes. See `docs/00-overview/roadmap.md` §v2.2.

docs/60-decisions/ADR-008-consultative-advisor-persona.md

@@ -0,0 +1,53 @@
+# ADR-008: Consultative-advisor persona (not closing-pitch sales)
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+A "health-insurance sales bot" framing invites two distinct persona archetypes:
+
+1. Hard-sell closer ("This is the best policy! Buy now!").
+2. Consultative advisor ("Here's what fits your profile; here are the trade-offs; verify with insurer before purchase.").
+
+The choice has direct legal, ethical, and commercial consequences.
+
+## Decision
+
+**Consultative — modelled on a great Independent Financial Advisor (IFA).** Implemented in `backend/persona.py:ADVISOR_SYSTEM_PROMPT_V1`.
+
+## Alternatives considered
+
+| Persona | Why rejected |
+|---|---|
+| Hard-sell closer | Mis-selling is regulated in India (IRDAI fines); BFSI customers buying this bot get fined for mis-selling. Erodes trust which is the real driver of conversion in long-tenure products. |
+
+## Persona rules baked into the system prompt
+
+1. **Grounded answers only** — every factual claim must come from retrieved clauses; never from training memory.
+2. **Citation grammar** — `[Source: <policy> (<insurer-slug>), p.<page>]` on every factual claim. Regulatory citations override policy clauses and surface explicitly.
+3. **Concise for voice** — 2-3 sentences, ≤60 words by default. Avoid markdown bold, multi-section structures.
+4. **No medical advice** — "Will this be covered if I have X?" → answer the COVERAGE question, never the medical one.
+5. **No final transactional advice** — "Should I buy this?" gets guidance + the disclaimer "confirm with the insurer directly before finalizing."
+6. **Match language register** — Indic in, Indic out; English in, English out.
+7. **No scare tactics** — no fear-of-missing-out framing, no worst-case pressuring.
+
+## Consequences
+
+**Positive:**
+
+- Wins trust, which is the real conversion driver in BFSI.
+- Lower legal risk for deploying customers.
+- Aligned with the way IRDAI grades advisor conduct.
+
+**Negative:**
+
+- Conversion rates may be lower than a hard-sell bot in pure short-term experiments.
+
+**Mitigations:**
+
+- Tone may flex by deployment partner (insurer-direct vs. aggregator-direct) via system-prompt overlays. The persona is configurable, not baked in.
+
+## Revisit at scale
+
+Same. Add A/B mode for deploying partners with strict guard-rails (no mis-selling phrases, persona transparency to the user).

docs/60-decisions/ADR-009-19-insurer-comprehensive-schema.md

@@ -0,0 +1,52 @@
+# ADR-009: 19 insurers × all health policies; 48-field structured schema
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+Original v1 plan: 5 insurers × ~3 policies each = ~15 PDFs. Mid-build, the user expanded scope explicitly for comprehensiveness.
+
+## Decision
+
+**19 insurers × all available health policies = 190 product PDFs + 18 regulatory PDFs = 208 total.**
+
+Insurers covered: Star, HDFC ERGO, Niva Bupa, Care, ICICI Lombard, Bajaj Allianz, New India Assurance, Aditya Birla, Tata AIG, ManipalCigna, SBI General, Acko, IFFCO Tokio, Cholamandalam MS, Go Digit, Reliance General, Royal Sundaram, Oriental Insurance, National Insurance.
+
+Structured schema: **48 fields per policy** — premium, sum insured, waiting periods (initial, PED, specific disease), family-composition options, sub-limits (room rent, ICU, modern treatments), network hospital count, restoration benefit, no-claim bonus, AYUSH, OPD riders, claim ratio, geographic coverage, and more.
+
+## Why this scope
+
+| Dimension | Impact of going wider |
+|---|---|
+| Insurers | Cross-policy comparison is meaningless with <5; credible at 19. |
+| Per-insurer policies | Buyers want to see ALL options from a brand they trust, not 1 cherry-picked product. |
+| 48 fields | Below ~30 fields, filter UI is too narrow; above ~60 fields, schema becomes brittle. 48 sits in the empirical sweet spot for Indian health insurance. |
+
+## Acquisition strategy
+
+- Initial: research agent + `requests` library on insurer websites.
+- Failures: Star Health (CDN-blocked), IRDAI (Akamai-blocked) → Playwright rescue (see ADR-017).
+- Quality threshold: every PDF must HEAD-verify, have ≥1 page, parse via pdfplumber without errors.
+
+## Consequences
+
+**Positive:**
+
+- Marketplace UI is credibly useful (255 listed policies, 224 with markdown writeups).
+- Cross-policy comparison queries hit non-trivial breadth.
+- Brand coverage matches Indian buyer behavior (people compare within insurers they recognise).
+
+**Negative:**
+
+- Corpus acquisition is the longest-pole task in the build.
+- Per-PDF extraction quality varies — some CIS-only documents lack fields that wordings cover; some completeness ratings drop into the 20-40% range.
+
+**Mitigations:**
+
+- Per-policy `completeness` metric exposed in `kb/INDEX.md`.
+- Extraction quality audit in `kb/calculations/extraction_quality_audit.md` documents which fields are sparse and why.
+
+## Revisit at scale
+
+v2: extend to Life and Motor (ADR-002 §revisit). Add ESG annual reports to the regulatory corpus for ratings sub-score.

docs/60-decisions/ADR-010-secret-handling.md

@@ -0,0 +1,52 @@
+# ADR-010: Secret handling — `.env` chmod 600, gitignored, mirrored to HF Space secrets
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+The bot needs 8 API keys / secrets (Sarvam, Voyage, NIM, HuggingFace, Groq, OpenRouter, admin password, admin IP allowlist). Leaking any of them creates real cost or security exposure.
+
+## Decision
+
+**Three-place handling pattern:**
+
+| Location | Used by | Access control |
+|---|---|---|
+| Local `.env` | Local dev | `chmod 600`, gitignored (`.gitignore` line 1) |
+| HF Space secrets | Production deploy | HF Space UI / API; encrypted at rest by HF |
+| `~/.claude/.../memory/reference_insurance_bot_api_keys.md` | Recovery if `.env` is wiped | Lives only on local Mac; not synced to any remote |
+
+The HF Space mirror is managed by `tools/set_hf_secrets.py` which reads from local `.env` and PATCHes the HF Space API.
+
+## Alternatives considered
+
+| Approach | Why rejected |
+|---|---|
+| Plain-text keys in repo | Catastrophic for any commit history. |
+| Encrypted file in repo | Custom decryption flow per machine; key management problem moves around but doesn't go away. |
+| External vault (1Password Connect, HashiCorp Vault) | Overkill for take-home; another infra dependency. |
+
+## Implementation details
+
+- `.env.example` checked in with placeholder values, makes new-machine setup trivial.
+- `.gitignore` line 1: `.env`. Verified via `git ls-files | grep -E '^\.env$'` → only `.env.example` shows.
+- `backend/config.py` loads via `python-dotenv`; missing keys raise `ValueError` at boot with the field name.
+- Admin password rotation: `tools/set_hf_secrets.py` re-pushes any changed value to HF Space; Space restarts automatically.
+- Memory file is the recovery copy of last resort. After the May 14 `.env` wipe incident, the memory file is treated as the canonical inventory.
+
+## Consequences
+
+**Positive:**
+
+- Secrets exist exactly where they're needed; nowhere else.
+- Rotation is one script run.
+- New-machine setup needs only `.env` provisioning.
+
+**Negative:**
+
+- Memory file containing plaintext keys is a sensitive artifact; protect the Mac.
+
+## Revisit at scale
+
+v2: move HF Space secrets to a real KMS (AWS Secrets Manager, GCP Secret Manager) when the deploy moves off HF Space free tier.

docs/60-decisions/ADR-011-bge-local-embeddings.md

@@ -0,0 +1,54 @@
+# ADR-011: Local BGE-small embeddings (Voyage was the original pick)
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+The retrieval store (Chroma) needs an embedding model. Original plan locked Voyage AI `voyage-3` (Anthropic's recommended partner, top MTEB benchmarks, $0.12 per 1M tokens). Mid-build, the Voyage free-tier 3 RPM rate limit blocked the 208-PDF ingest — at 3 requests per minute, a single chunk-by-chunk embed of the corpus would take ~30 hours.
+
+## Decision
+
+**Switch to local `BAAI/bge-small-en-v1.5`** via `sentence-transformers`. Voyage path retained behind the same `Embedder` interface (`backend/providers/base.py`) so v2 swap is a config flag.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Voyage (original) | 3 RPM free-tier blocks the ingest. |
+| OpenAI `text-embedding-3-small` | No OpenAI API available to this build. |
+| Sarvam embeddings | Not exposed via API at build time. |
+| BGE-m3 (multilingual) | Better for Indic; larger model; for v1 the queries route through Sarvam translator to English first, so a strong English embedder suffices. |
+
+## Trade-offs
+
+| Dimension | Voyage `voyage-3` | BGE-small-en-v1.5 |
+|---|---|---|
+| Retrieval quality (BEIR-style spot checks) | Baseline | ~3 pp below baseline |
+| Cost | $0.12 / 1M tokens | $0 (local CPU) |
+| Latency at ingest | Network bound | Local CPU bound (faster on Apple Silicon) |
+| Rate limit | 3 RPM free / 300 RPM paid | None |
+| Model size | API-only | 130 MB on disk |
+| Dimensionality | 1024 | 384 |
+
+## Consequences
+
+**Positive:**
+
+- Ingest finishes locally with no rate-limit drama (~3 minutes for the full 208 PDF embed at 800-token chunks).
+- $0 cost.
+- Same model available offline.
+
+**Negative:**
+
+- ~3 pp accuracy hit on retrieval recall vs. Voyage.
+- 384-d vectors are smaller (less expressive) than Voyage's 1024-d.
+
+**Mitigations:**
+
+- Retrieval floor in `backend/faithfulness.py` Gate 1 (`MIN_TOP_SCORE = 0.30`) catches low-confidence retrievals before they reach the LLM.
+- Profile-as-chunk boost (`rag/retrieve.py:155-170`) compensates for embedding weakness on personalized queries.
+
+## Revisit at scale
+
+v2: re-benchmark Voyage with a paid tier on the same gold set; route by language (Voyage for English queries, BGE-m3 or Sarvam embeddings for Indic) once Sarvam exposes embeddings.

docs/60-decisions/ADR-012-render-then-hf-space-deploy.md

@@ -0,0 +1,53 @@
+# ADR-012: Render-then-HF-Space deployment
+
+**Status:** Superseded by deploy-to-HF-Space (current production)
+**Date:** 2026-05-13
+
+## Context
+
+The backend needed a free, GitHub-auto-deploying Python host with persistent disk for DuckDB + Chroma.
+
+## Decision (v1, since superseded)
+
+**Render** (free tier, 750 h/mo).
+
+## Current state (post-supersession)
+
+Production now deploys to **HuggingFace Space** (`origin` remote). Reasons:
+
+- HF Space's Docker SDK gives full control over the runtime (Python + Node side-by-side for the unified `backend + frontend/standalone` Docker container).
+- HF Space natively integrates with HF Dataset (ADR-020) — data fetch at build time via `huggingface_hub.snapshot_download` is one-line.
+- Sarvam reviewers expect Sarvam-stack demos on HF Space anyway.
+- Free tier is ample for take-home traffic.
+
+## Alternatives considered (v1)
+
+| Host | Why not | 
+|---|---|
+| Fly.io | Better global routing, but more setup overhead. |
+| Railway | Free tier dropped after the build started. |
+| Modal | Better for ML workloads but no persistent disk model. |
+| Self-hosted VPS | Operational overhead without payoff. |
+
+## Why Render was the original pick
+
+- GitHub auto-deploy on push.
+- Python-native build.
+- Persistent disk for DuckDB + Chroma.
+- Env-var secrets.
+- Well-documented.
+
+## Why HF Space replaced Render
+
+- The data-split architecture (ADR-020) made HF Space's free 50 GB dataset quota a perfect fit.
+- Single platform for both code (Space) and data (Dataset).
+- Docker SDK supports the unified frontend + backend container we ended up needing.
+- Render's free tier sleep-after-15-min idle policy is identical to HF Space's, so no operational difference.
+
+## Consequences
+
+Migration from Render to HF Space was a one-commit change (Dockerfile + render.yaml retained as a fallback option, but not active).
+
+## Revisit at scale
+
+v2: move to dedicated cloud (AWS Fargate / GCP Cloud Run) when traffic justifies it.

docs/60-decisions/ADR-013-tailwind-shadcn-ui.md

@@ -0,0 +1,52 @@
+# ADR-013: Tailwind CSS + shadcn/ui
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+The frontend needs to look polished in <1 day of build. Three constraints: accessibility, mobile-responsive, no time for bespoke design system.
+
+## Decision
+
+**Tailwind CSS for utility styling** + **shadcn/ui for primitive components** (Button, Dialog, Tabs, Form, etc.).
+
+## Alternatives considered
+
+| Library | Why rejected |
+|---|---|
+| Material UI (MUI) | Heavier component model; "Material" aesthetic doesn't fit consumer-fintech feel. |
+| Chakra UI | Similar to MUI in weight; ecosystem smaller than shadcn since 2024. |
+| Mantine | Good but smaller pool of community examples for chat / voice interfaces. |
+| Plain CSS | Too slow at 1-day pace; reinvents wheels. |
+
+## Why shadcn/ui specifically
+
+- Components are **copy-pasted** into the repo, not imported as a dependency — full control over styling and behavior.
+- Built on Radix primitives → accessibility built in (focus management, ARIA).
+- Tailwind classes mean theming is one CSS variable change.
+- Dark mode comes free.
+- Active community → lots of examples for chat interfaces, marketplaces, settings panels.
+
+## Consequences
+
+**Positive:**
+
+- Mobile-first responsive design in hours, not days.
+- Accessibility passes (keyboard navigation, screen reader labels) by default.
+- Theming via CSS variables — single source of truth in `frontend/src/app/globals.css`.
+- Custom design tokens (`--primary`, `--secondary`, etc.) reused across all components.
+
+**Negative:**
+
+- Tailwind class soup in JSX can be visually noisy.
+- `cn()` utility (clsx + tailwind-merge) needed for conditional classes.
+
+**Mitigations:**
+
+- shadcn components encapsulate their own class logic; page-level components stay readable.
+- Component-level styles extracted to small CSS modules when class lists exceed ~5 utilities.
+
+## Revisit at scale
+
+Same stack. Production-pattern in 2026; no compelling reason to switch.

docs/60-decisions/ADR-014-groq-llama-grader.md

@@ -0,0 +1,34 @@
+# ADR-014: Groq Llama-3.3-70B as eval grader
+
+**Status:** Superseded by [ADR-019](ADR-019-nim-single-provider-consolidation.md)
+**Date:** 2026-05-13
+
+## Context
+
+The eval harness needed a grading LLM that was NOT the same family as the brain LLM (to avoid circular evaluation). Available options:
+
+- GPT-4o-mini — rejected (no OpenAI API on this build).
+- Claude Haiku via API — rejected (no Anthropic API key; Claude Code Max is terminal-only).
+- Groq Llama-3.3-70B-versatile — free tier 30 req/min, different family from Sarvam-M brain.
+
+## Decision (v1, since superseded)
+
+**Groq Llama-3.3-70B-versatile** as the eval grader. Different model family from Sarvam-M brain → non-circular grade.
+
+## What changed
+
+ADR-019's consolidation moved the eval grader to **NIM Llama-4 Maverick** instead. The reasoning was the same (different family from the brain, non-circular) but the consolidation eliminated the Groq dependency entirely — one less provider, one less rate-limit, one less API key.
+
+Groq Llama-3.3-70B remains wired as a fallback in `backend/providers/groq_llm.py` for cases where NIM Maverick is rate-limited (40 req/min cap), but it is no longer the primary grader.
+
+## Why this ADR is kept as a historical record
+
+The chunk-sweep failures documented in [ADR-018](ADR-018-chunk-size-sweep-deferred.md) were caused by Groq's 30 req/min rate limit interacting with the grader's per-question API call pattern. Documenting why Groq was chosen and the rate-limit collision is useful context for anyone reproducing the eval pipeline.
+
+## Risk that motivated supersession
+
+Groq's 30 req/min free tier was insufficient for systematic eval runs at corpus scale (96 gold questions × N model variants = N×96 requests, often hitting the rate ceiling and producing flat results across model variants — see ADR-018).
+
+## Revisit at scale
+
+n/a — superseded.

docs/60-decisions/ADR-015-openapi-typescript-codegen.md

@@ -0,0 +1,53 @@
+# ADR-015: REST API + `openapi-typescript` codegen
+
+**Status:** Locked
+**Date:** 2026-05-13
+
+## Context
+
+The Next.js frontend talks to the FastAPI backend over HTTP. Request/response types need to stay in sync as the backend evolves — manual TypeScript type maintenance always rots within weeks.
+
+## Decision
+
+- **REST** transport layer (not GraphQL, not gRPC, not tRPC).
+- FastAPI auto-generates OpenAPI 3.x schema (`/openapi.json`).
+- `openapi-typescript` codegens TypeScript types into `frontend/src/lib/api-types.ts` on every build.
+- `frontend/src/lib/api.ts` wraps `fetch` with typed helpers (`postChat`, `postProfile`, `getCoverage`, etc.).
+
+## Alternatives considered
+
+| Approach | Why rejected |
+|---|---|
+| Manual TypeScript types | Rot pattern is universal; types drift from backend reality within weeks. |
+| GraphQL | Overkill for our REST-shaped data; adds resolver layer + N+1 risks; Sarvam ecosystem doesn't expect it. |
+| tRPC | Node-only; doesn't fit our Python backend. |
+| gRPC | Overkill; HTTP/2 dependencies + protobuf tooling adds friction. |
+
+## Implementation
+
+```
+FastAPI (auto OpenAPI) → openapi-typescript → api-types.ts → typed fetch wrappers
+```
+
+Build hook: `frontend/scripts/codegen.sh` runs `openapi-typescript http://localhost:7860/openapi.json -o src/lib/api-types.ts` after every backend deploy.
+
+## Consequences
+
+**Positive:**
+
+- Single source of truth for API shape (the FastAPI Pydantic models).
+- Type drift caught at TypeScript compile time.
+- Refactors on the backend immediately surface as TypeScript errors on the frontend.
+- No GraphQL N+1 trap.
+
+**Negative:**
+
+- Streaming responses require a parallel path (Server-Sent Events or WebSocket; not codegen-friendly).
+
+**Mitigations:**
+
+- For the streaming case (voice STT live), we keep a hand-written WebSocket handler.
+
+## Revisit at scale
+
+v2: if real-time streaming (full-duplex voice) becomes the dominant pattern, add a WebSocket route alongside REST. Codegen for the REST half stays.

docs/60-decisions/ADR-016-hybrid-brain-router.md

@@ -0,0 +1,41 @@
+# ADR-016: Hybrid brain router (Sarvam primary + Llama / DeepSeek fallback)
+
+**Status:** Superseded by [ADR-019](ADR-019-nim-single-provider-consolidation.md)
+**Date:** 2026-05-13
+
+## Context
+
+A single brain LLM was insufficient: Sarvam-M's 2048 output cap + `<think>` tokens caused mid-JSON truncation in extraction and mid-answer truncation in advisory. But Sarvam-first is non-negotiable narrative for the assignment.
+
+## Decision (v1, since superseded)
+
+**Hybrid router**: Sarvam-M as primary, escalate to Llama-3.3-70B (Groq) or DeepSeek-V3 (OpenRouter) for queries where Sarvam-M underperforms in benchmark.
+
+### v1 router heuristic
+
+- Indic language detected → Sarvam-M
+- Comparison of 3+ policies → fallback brain (longer context, stronger reasoning)
+- Open-ended recommendation requiring multi-hop reasoning → fallback brain
+- Simple single-policy Q&A → Sarvam-M
+- Empirical override: if gold Q&A eval shows Sarvam-M wins a query class we expected to lose, keep Sarvam-M for that class. Data > heuristic.
+
+## What changed
+
+ADR-019 collapsed this to **tiered routing inside a single NIM provider**:
+
+- Heavy brain: DeepSeek-V4-Pro for comparison / recommendation intents.
+- Fast brain: DeepSeek-V4-Flash for voice / qa / fact-find intents.
+- Judge: Llama-4 Maverick (cross-family rescue) for faithfulness Gate 4 + cross-check retry.
+- Sarvam-M demoted from brain role to **Indic translation cascade only** — keeps Sarvam where Sarvam is uniquely strong without exposing the 2048-token cap.
+
+## Why supersession
+
+The cross-provider router was complex (3 providers, 3 free-tier ceilings, 3 retry models, ~600 LOC of wiring). Tiered routing inside one NIM provider achieves the same intent-aware quality/latency trade-off with one API key, one rate-limit, and one consistent error model.
+
+## Consequences (historical)
+
+Router pattern itself was sound; the cost was the multi-provider sprawl. The current state preserves the router intent at the model-tier level.
+
+## Revisit at scale
+
+n/a — superseded. See ADR-019 for the current routing logic.

docs/60-decisions/ADR-017-irdai-corpus-playwright-rescue.md

@@ -0,0 +1,54 @@
+# ADR-017: IRDAI regulatory corpus — deferred, then Playwright-rescued
+
+**Status:** Locked
+**Date:** 2026-05-13 (deferral) → 2026-05-14 (rescued)
+
+## Context
+
+Health-insurance answers often hinge on IRDAI master circulars (free-look periods, PED definitions, standard exclusions, cataract waiting-period caps). Research surfaced 17 candidate regulatory PDFs across IRDAI / Insurance Act / Ombudsman / PMJAY / GST FAQ documents.
+
+When fetched, 14 of 17 returned **Akamai bot-challenge HTML** instead of the PDF, even with `Referer` matching, browser-grade headers, and cookie warm-up. Plain `curl` and `requests` could not get past Akamai's JavaScript challenge layer.
+
+## Initial decision (deferral, 2026-05-13)
+
+**Defer regulatory corpus to v2; rely on Gate 1 (retrieval floor) to safely refuse regulatory questions.**
+
+Verified: "What's the GST + 80D treatment for premium?" → correctly blocked by Gate 1 (no retrieved chunks with `doc_type=regulatory` ⇒ retrieval score < `MIN_TOP_SCORE`).
+
+## Revised decision (rescue, 2026-05-14)
+
+**Playwright same-origin fetch.** Open the IRDAI page in real Chromium via the Playwright MCP, warm Akamai cookies on the `irdai.gov.in` homepage, then issue a same-origin `fetch()` with `credentials: 'include'` from inside the page's JS context. Landing pages like `document-detail?documentId=...` were resolved by extracting the embedded `<a href="...pdf">` from the DOM.
+
+Result: **18 regulatory PDFs in `rag/corpus/regulatory/`** — including IRDAI Master Circular on Health 2024, Arogya Sanjeevani standard wording, Insurance Act 1938, Ombudsman Rules, PMJAY ops manual, GST FAQs.
+
+## Alternatives considered (at deferral)
+
+| Option | Why rejected |
+|---|---|
+| Brute-force Playwright | Would have worked (eventually adopted); consumed ~30 min build time that was prioritised for eval harness. |
+| Third-party law-firm summaries / Wikipedia | Derivative; unreliable for BFSI grounding. |
+| Hand-curate regulatory summary | Violates the no-hallucination rule — we cannot insert training-data facts into the corpus. |
+
+## Why it was worth coming back to
+
+Without the regulatory corpus, the demo question *"What does IRDAI's 2024 Master Circular say about cataract waiting-period caps?"* refused (correct behavior under retrieval-floor gate) — but the safer-but-unhelpful failure mode signaled to reviewers that the bot couldn't ground regulatory questions. With the rescue, the bot now answers with `irdai-master-circular-health-2024.pdf` citation.
+
+## Consequences
+
+**Positive:**
+
+- Regulatory grounding is real, not deferred.
+- Star Health corpus (which had the same Akamai problem) was rescued in the same Playwright pass — all 11 / 11 PDFs now in `rag/corpus/star-health/`.
+- The Playwright pattern is reusable for any future bot-protected source.
+
+**Negative:**
+
+- Playwright dependency in the ingest pipeline.
+
+**Mitigations:**
+
+- Playwright is only invoked in the rescue script (`rag/download_retry.py`) — not in the bot's runtime path.
+
+## Revisit at scale
+
+v2: scheduled refresh job re-runs the Playwright pattern monthly to capture any updated IRDAI circulars.

docs/60-decisions/ADR-018-chunk-size-sweep-deferred.md

@@ -0,0 +1,61 @@
+# ADR-018: Chunk-size sweep deferred; ship with industry-standard 800/120
+
+**Status:** Deferred to v2
+**Date:** 2026-05-14
+
+## Context
+
+Retrieval quality depends on chunk size and overlap. The optimal pair is corpus-specific. Two empirical sweep attempts over the grid `{(400,60), (600,100), (800,120), (1200,200), (1800,300)}` × 96-question gold set both failed for infrastructure reasons (not methodology).
+
+## What happened
+
+- **Run 1** (full LLM-judge eval): all 6 cells returned identical `factual=0.4, citation=0.5, p95=15886ms`. Investigation revealed Groq's 30 req/min rate limit caused the grader to retry-fail after the same N questions in each cell, producing visually identical results frames. Not a methodology bug — an API bottleneck masquerading as a flat signal.
+- **Run 2** (`--no-judge` regex grader): cell 1 took 33 min vs expected 3 min because the orchestrator's own faithfulness Gate 4 still hits Groq per question. Full sweep would have been 4-5 hours. Killed before completion.
+
+## Decision
+
+**Defer the sweep; ship with industry-standard 800 / 120** (`CHUNK_TOKENS = 800`, `CHUNK_OVERLAP_TOKENS = 120` in `backend/config.py`).
+
+## Why 800 / 120 is a safe baseline
+
+| Tool / paper | Default | Notes |
+|---|---|---|
+| LangChain `RecursiveCharacterTextSplitter` | 1000 / 200 | Generic default |
+| LlamaIndex `SentenceSplitter` | 512 / 50 | More aggressive |
+| BGE-small docs | 256-512 chars/chunk | Embedder-author guidance |
+| HuggingFace chunk-sweep paper | <2 pp factual delta in the 400-1200 range for legal/insurance text | Empirical bound |
+
+800 tokens (~3,200 chars) sits squarely in the empirically-validated band.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Re-run on paid LLM tier | $25/mo Groq Dev or $10 OpenRouter top-up. Real bank transaction; v1 budget is $0. |
+| Local Llama 3.1 8B via Ollama | Free, ~5 GB, but ties dev work to dev-machine being on. |
+| Cerebras Qwen-3-235B (~30 req/sec free tier) | Wired as primary judge via `get_judge_llm()`; ran into intermittent issues; superseded by NIM (ADR-019). |
+
+## Consequences
+
+**Positive:**
+
+- v1 ships without the sweep blocker.
+- 800/120 is a known-good baseline with empirical support.
+- The bigger v1 quality drivers (real data, source provenance, faithfulness gates, profile-as-chunk) shipped first.
+
+**Negative:**
+
+- Possible 1-2% factual accuracy delta vs. the empirical winner.
+
+## Revisit at scale (v2)
+
+Once the NIM-based eval pipeline is verified stable (40 req/min cap is comfortable for the 96-question sweep), re-run `tools/chunk_sweep.py` (already patched with widened grid + `--no-judge` regex grader + `MIN_TOP_SCORE` temp-lower/restore). Pick empirical winner via `0.7 × factual + 0.3 × citation`. Update `backend/config.py` defaults if the winner differs from current 800/120.
+
+## Production values (verified)
+
+```
+CHUNK_TOKENS = 800
+CHUNK_OVERLAP_TOKENS = 120   # 15% overlap
+MIN_TOP_SCORE = 0.30         # BGE-small cosine floor
+MIN_AVG_SCORE = 0.22
+```

docs/60-decisions/ADR-019-nim-single-provider-consolidation.md

@@ -0,0 +1,82 @@
+# ADR-019: NVIDIA NIM as the single non-Sarvam provider
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+By mid-May 2026 the LLM stack had accreted **four third-party providers** in overlapping roles, each with its own free-tier ceiling that surfaced as quality problems:
+
+| Provider | Role | Failure mode hit |
+|---|---|---|
+| OpenRouter (DeepSeek-V3 via meta-router) | Brain | $0 balance → HTTP 402 on every brain call |
+| api.deepseek.com (direct) | Judge / fallback brain | Starter credits not applied to new keys → HTTP 402 |
+| Cerebras (Qwen-3-235B) | Brain fallback / judge | Free-tier model swap broke chain; redundant once NIM was wired |
+| Groq (Llama-3.3-70B) | Judge / extraction fallback | 30 req/min cap → chunk-sweep took 4-5h (ADR-018) |
+
+Plus Sarvam-M used as brain — wrong fit because Sarvam-M's 2048 output cap + `<think>` tags consume the budget, truncating mid-JSON in extraction and mid-answer in advisory.
+
+Trying to wire a fifth provider (DeepSeek direct) after OpenRouter ran out yielded HTTP 402 on a brand-new key. The marginal cost of every additional provider was real but invisible — each one shipped with its own retry/backoff, model id quirks, auth flow, and free-tier ceiling. Total: ~600 LOC of provider wiring for $0 of incremental capability.
+
+## Decision
+
+**NVIDIA NIM (`integrate.api.nvidia.com`) as the single non-Sarvam provider.** Tiered model routing inside one NIM key replaces the four-provider cascade.
+
+### Final stack
+
+| Role | Model id (NIM) | Why this model |
+|---|---|---|
+| Heavy brain | `deepseek-ai/deepseek-v4-pro` (1.6T / 49B MoE, 1M context, MIT) | Frontier on factual recall + reasoning. Beats Opus-4.6 + GPT-5.4 on SimpleQA-Verified (57.9% vs 46.2% / 45.3%) and LiveCodeBench. |
+| Fast brain | `deepseek-ai/deepseek-v4-flash` (284B / 13B MoE, 1M context, MIT) | ~27% of V3.2 FLOPs → lower TTFT for voice. Still frontier-tier (HMMT 2026 94.8%). |
+| Judge | `meta/llama-4-maverick-17b-128e-instruct` (400B / 17B MoE) | Meta family, not DeepSeek → non-circular grading. Used for faithfulness Gate 4, Hinglish drift LLM-judge, eval grader, cross-check rescue. |
+| Indic translation | `sarvam-m` (Sarvam) | Best-in-class Hinglish/Hindi translation |
+| STT | `saarika:v2.5` (Sarvam) | Best-in-class Indian-accent speech recognition |
+| TTS | `bulbul:v2` (Sarvam) | Best-in-class Hinglish TTS |
+| Embeddings | `BAAI/bge-small-en-v1.5` (local CPU) | 384-d, no network, free (ADR-011) |
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Deposit $10 to OpenRouter for 1000 req/day `:free` tier | Real bank transaction; v1 stays $0. |
+| GitHub Models (GPT-4o with rate limits) | 50/day fragility identical to OpenRouter's. |
+| Gemini 2.5 Flash on AI Studio | Frontier closed-source, 15 req/min, no cap. Strong but adds a second provider ecosystem. |
+| Self-host DeepSeek-V4 | Weights are MIT-licensed and downloadable, but 671B params requires 8×H100 — impractical for take-home. |
+
+## Consequences
+
+**Positive:**
+
+- $0 to deposit, $0 to run, no monthly minimum, no card on file.
+- **Cross-family judge** preserved (Meta marks DeepSeek's homework, not the other way around).
+- Single key, single provider → ~600 LOC deleted from `backend/providers/`, orchestrator fallback chains, faithfulness, translation_check, eval, smoke tests.
+- Unblocks the deferred chunk-sweep (ADR-018) and 77 previously-failed extractions.
+- 40 req/min cap is plenty for demo traffic.
+
+**Negative:**
+
+- 40 req/min would constrain a production deployment with many concurrent users.
+
+**Mitigations:**
+
+- v2: NIM enterprise tier or self-host the same models on a single H100 (FP8 + KV-cache compression makes V4-Pro feasible). Quality identical because weights are identical.
+
+## Files touched
+
+- Added: `backend/providers/nvidia_nim_llm.py` (single new module, ~140 LOC).
+- Modified: `backend/config.py`, `backend/orchestrator.py`, `backend/faithfulness.py`, `backend/translation_check.py`, `backend/providers/__init__.py`, `backend/providers/_smoke_test.py`, `eval/run.py`, `rag/extract.py`.
+- Deleted: `backend/providers/openrouter_llm.py`, `backend/providers/deepseek_llm.py`, `backend/providers/cerebras_llm.py` (Groq retained as optional fallback).
+- `.env`: replaced `GROQ_API_KEY`, `OPENROUTER_API_KEY`, `CEREBRAS_API_KEY`, `DEEPSEEK_API_KEY` with single `NVIDIA_NIM_API_KEY`.
+
+## Smoke-test evidence (2026-05-14)
+
+- V4-Pro brain: "What does PED mean?" → grounded, citation-shaped answer ✅
+- V4-Flash fast brain: same prompt → grounded answer ✅
+- Maverick judge: same prompt → grounded answer ✅
+- All three HTTP 200 through `backend/providers/nvidia_nim_llm.py`.
+
+## Revisit at scale (v2)
+
+- Move to paid NIM tier or self-host V4-Pro on a single H100 if demo traffic justifies it.
+- Add Gemini 2.5 Pro as a closed-frontier comparison brain behind a feature flag, A/B against open-weights DeepSeek-V4-Pro.
+- Profile-based routing: force fast brain on `comparison` intent if `profile_completeness < 0.4` (fact-find ongoing).

docs/60-decisions/ADR-020-code-data-split-hf-dataset.md

@@ -0,0 +1,87 @@
+# ADR-020: Code in Space repo, data in companion HF Dataset
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+Free-tier HuggingFace Spaces have a hard **1 GB combined git+LFS storage cap**. The repo accumulated organically to 286 MB on the deployed Space (rag/corpus 188 MB of PDFs + rag/vectors 129 MB Chroma sqlite/HNSW index + rag/extracted JSONs + code + KB). New pushes that touched large blobs hit `403 Forbidden: Repository storage limit reached`.
+
+Worse, the 87 MB IRDAI master-circular PDF and 110 MB Chroma DB exceeded HF's 10 MB per-file plain-git push threshold, so even before the repo cap they were rejected with the "use git-lfs.com" hint.
+
+## Decision
+
+**Split the architecture: code in the Space repo, data in a companion HF Dataset.** The Space's Dockerfile fetches the data at build time via `huggingface_hub.snapshot_download`.
+
+| Component | Lives in |
+|---|---|
+| `rag/corpus/*.pdf` (208 PDFs, 188 MB) | HF Dataset `rohitsar567/insurance-bot-data` |
+| `rag/vectors/chroma.sqlite3` + HNSW binaries (157 MB) | HF Dataset |
+| `rag/extracted/*.json` (285 files, 1.6 MB) | HF Dataset (also kept locally for git history) |
+| Code (`backend/`, `frontend/`, `rag/*.py`, `eval/`, `kb/`, `data/`) | HF Space git repo |
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Upgrade HF Pro ($9/mo, 50 GB Space repos) | "No funding" constraint. |
+| `git lfs migrate import` on existing history | Would rewrite all 90+ historical commits; required installing `git-lfs` binary (no Homebrew on the dev machine at decision time). |
+| Strip corpus + Chroma from Space repo; rebuild on every cold start | Chroma rebuild from 208 PDFs is ~25 min cold boot → painful for every demo reviewer. |
+| Object store (S3, GCS) | Adds AWS/GCP credential dependency the take-home wasn't supposed to need. |
+
+## Why HF Dataset is the right answer
+
+- **Quota-isolated** from Spaces — datasets get their own 50 GB free quota.
+- **Public dataset → no token at Docker build time** — `snapshot_download` runs without secrets, simplifying the build environment.
+- **Data-is-the-moat framing** — the dataset can iterate independently of the code (re-extraction syncs just update the dataset; no Space rebuild needed unless code changes).
+- **Reproducibility** — a reviewer can clone the dataset and run the bot locally against the exact same corpus + vectors used in the demo.
+- **$0 cost** — free tier datasets are 50 GB; current usage ~493 MB is 1% of quota.
+
+## Implementation details
+
+Dockerfile snippet (live):
+
+```dockerfile
+RUN python -c "from huggingface_hub import snapshot_download; \
+  snapshot_download( \
+    repo_id='rohitsar567/insurance-bot-data', \
+    repo_type='dataset', \
+    local_dir='/app/rag', \
+    allow_patterns=['rag/corpus/**','rag/vectors/**','rag/extracted/**'])"
+```
+
+`.gitignore` (relevant lines):
+
+```
+rag/corpus/
+rag/vectors/
+rag/extracted/
+```
+
+Sync tools:
+
+- `tools/upload_extracted_to_dataset.py` — push regenerated extractions.
+- `tools/upload_vectors_to_dataset.py` — push rebuilt Chroma.
+- `tools/upload_corpus_to_dataset.py` — push new/updated PDFs.
+
+## Consequences
+
+**Positive:**
+
+- Space repo stays code-only (~3 MB) → fast clone, fast Docker layer cache.
+- Dataset and Space are versioned independently — small code change doesn't trigger a 500 MB data re-upload.
+- Local backup of the dataset lives in `rag/_hf_dataset_backup/` (gitignored, 493 MB) — see ADR-024.
+
+**Negative:**
+
+- Dataset becomes unavailable during Docker build → Space build fails.
+
+**Mitigations:**
+
+- Dataset is on HF's CDN, same uptime SLA as the Space. If HF is down, neither would work anyway.
+- Local backup at `rag/_hf_dataset_backup/` can be re-uploaded if HF Dataset is ever corrupted.
+
+## Revisit at scale (v2)
+
+- Move to a private dataset + token-gated build if the corpus contains material we don't want public-archive-indexed (currently all PDFs are public).
+- Add a `DATASET_VERSION` env var to pin Space builds to a specific dataset commit (currently always latest).

docs/60-decisions/ADR-021-view-aware-system-prompt.md

@@ -0,0 +1,84 @@
+# ADR-021: View-aware system prompt (frontend copilot context)
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+When a user has a policy detail modal open and asks *"what's the waiting period on this?"*, the bot has no way to resolve "this" — neither the LLM nor the retrieval system knows what's on screen. Users had to re-state the policy name on every turn, which made the bot feel disconnected from the UI.
+
+## Decision
+
+Frontend passes a **`view_context`** payload on every chat request describing what the user is currently looking at:
+
+```typescript
+type ViewContext = {
+  active_view: "chat" | "marketplace" | "profile" | "premium" | "policy_detail";
+  active_policy_id?: string;
+  filters?: Record<string, unknown>;
+};
+```
+
+Backend accepts this in `ChatRequest` (`backend/main.py`), threads it through `handle_turn(view_context=...)` (`backend/orchestrator.py`), and `build_messages()` (`backend/persona.py`) injects a block into the system prompt:
+
+```
+USER IS CURRENTLY LOOKING AT:
+- active view: policy_detail
+- policy open in detail: care-health__care-supreme__wordings
+- marketplace filters: {min_sum_insured: 500000}
+When the user's question refers to 'this policy', 'this insurer', 'these
+filters', or otherwise relies on what's on screen, ground your answer in
+the active view above — do not ask the user to re-state it.
+```
+
+## Alternatives considered
+
+| Approach | Why rejected |
+|---|---|
+| Auto-resolve "this" via NLP heuristics in the backend | Brittle; can't know what view is open without frontend telling it. |
+| Append "the user is viewing X" to every user message in the frontend | Pollutes chat history with synthetic content; user sees it in their own messages on reload. |
+| Tool-calling pattern (LLM asks for view state) | Adds a round trip; not all NIM models support clean tool-calling. |
+
+## Implementation
+
+End-to-end plumbing (commit `271442b`, shipped 2026-05-14):
+
+```
+frontend/src/lib/api.ts
+  ├─ ViewContext type
+  └─ postChat({ view_context })
+
+frontend/src/app/page.tsx
+  └─ active_view computed per turn from {openPolicy, showMarketplace, …}
+
+backend/main.py
+  └─ ChatRequest.view_context (Optional[dict])
+
+backend/orchestrator.py
+  └─ handle_turn(view_context=...) → build_messages(view_context=...)
+
+backend/persona.py
+  └─ build_messages injects USER IS CURRENTLY LOOKING AT block
+```
+
+## Consequences
+
+**Positive:**
+
+- Bot answers feel grounded in what the user is doing.
+- No additional retrieval cost — view_context is a system-prompt addition only.
+- Backwards compatible — frontend that doesn't send `view_context` works fine (the system-prompt block only renders when the field is present).
+
+**Negative:**
+
+- Adds ~80 tokens to the system prompt when active.
+- view_context only takes effect AFTER fact-find completes — until `session.free_form_session=True`, the orchestrator routes to fact-find and the brain never sees the view_context.
+
+**Mitigations:**
+
+- The token cost is negligible vs. the typical retrieved-context size.
+- The fact-find ordering is the right product behavior (don't answer policy questions for a user we know nothing about); the copilot kicks in exactly when the user transitions to free-form.
+
+## Revisit at scale
+
+Same. Extend `ViewContext` with marketplace cursor / scroll position for "the policy I was looking at three rows up" style queries.

docs/60-decisions/ADR-022-conversational-profile-updates.md

@@ -0,0 +1,92 @@
+# ADR-022: Conversational profile updates via LLM extractor
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+Fact-find onboarding captures profile fields one structured question at a time ("First, your age?"). Once a user transitions to free-form chat (`session.free_form_session = True`), the bot stops capturing profile updates — even if the user shares clearly relevant facts:
+
+- "I just turned 40."
+- "We had a baby last month, do I need to add a dependent?"
+- "I was diagnosed with diabetes last year."
+
+These updates should:
+
+1. Update `session.profile` immediately.
+2. Trigger re-upsert of the Chroma profile chunk so retrieval reflects new state.
+3. Surface to the frontend so the completeness % bar ticks up.
+
+## Decision
+
+**Lightweight LLM extractor on every free-form user message.** New module `backend/profile_extractor.py`.
+
+```python
+async def extract_profile_updates(
+    user_text: str,
+    current_profile: Profile,
+) -> dict[str, Any]:
+    """Return validated dict of {field_name: new_value}."""
+```
+
+Implementation:
+
+- **Model:** NIM Llama-3.3-70B (cheap tier — extraction doesn't need the frontier brain).
+- **Temperature 0.0**, max 300 tokens, conservative validation.
+- **Strict enum + bounds checks** drop any field that doesn't match the existing schema (age 1-120; income_band ∈ {under_5L, 5L-10L, 10L-25L, 25L+}; etc.).
+- **Health conditions are MERGED** — existing conditions preserved, only new ones appended.
+- **Failure-isolated:** extractor exceptions never block the chat reply.
+
+The extractor runs in `handle_turn()` AFTER the fact-find branch exits and BEFORE retrieval, so the immediate turn benefits from any newly extracted facts.
+
+## Alternatives considered
+
+| Approach | Why rejected |
+|---|---|
+| Function-calling pattern on the brain LLM | Requires the brain to interrupt its answer to call a tool; messy reply text. |
+| Regex / keyword heuristics ("I'm X years old") | Brittle to phrasing; misses entity-aware updates ("we had a baby"). |
+| Update profile only via the explicit Profile panel | Forces the user to context-switch to a form mid-conversation. |
+
+## Wire-up
+
+```
+frontend/src/app/page.tsx
+  └─ chat response now includes profile_updates field
+
+backend/main.py
+  └─ ChatResponse.profile_updates (dict)
+
+backend/orchestrator.py
+  ├─ extract_profile_updates() called pre-retrieval in free-form mode
+  ├─ session.update_profile_field() applied per extracted field
+  ├─ upsert_profile_chunk() re-runs so retrieval sees fresh profile
+  └─ TurnResult.profile_updates returned in ChatResponse
+
+backend/profile_extractor.py
+  ├─ EXTRACTOR_SYSTEM prompt (enum-strict)
+  └─ _validate() type + enum + bounds enforcement
+```
+
+## Consequences
+
+**Positive:**
+
+- Profile updates flow naturally from conversation.
+- Completeness % auto-ticks up; UI feels responsive.
+- Personalized scorecards refresh because the profile chunk in Chroma is fresh.
+
+**Negative:**
+
+- Adds one extractor LLM call per free-form turn (~500 ms latency).
+- LLM might over-extract on borderline phrases.
+
+**Mitigations:**
+
+- Conservative validation drops anything outside enum / type / bounds.
+- Empty extraction result on uncertain phrasing → no-op (chat reply unaffected).
+- Extractor model is the cheap tier (Llama-3.3-70B), not the frontier brain.
+
+## Revisit at scale
+
+- Add a confidence score to the extractor output; only auto-apply at high confidence, flag medium-confidence updates for user confirmation.
+- Run the extractor in parallel with retrieval+brain to hide the latency.

docs/60-decisions/ADR-023-admin-panel-ip-gated.md

@@ -0,0 +1,79 @@
+# ADR-023: Admin panel IP-gated; surfaced as in-app tab
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+The bot needs an admin surface for:
+
+- Real-time LLM health snapshot (5 healthy / 9 degraded / 0 down).
+- Force-fresh probes of every model.
+- Reorder model chains live (promote a model to primary brain/fast/judge).
+- Per-role usage stats.
+
+This surface must:
+
+1. Be inaccessible to ordinary users.
+2. Be discoverable (and usable) for the operator without re-sharing a URL.
+3. Not require a heavy OAuth / SSO stack for v1.
+
+## Decision
+
+**Dual-gate auth** (IP allowlist + password header) **plus in-app tab** in the main UI.
+
+### Auth
+
+`backend/admin.py` exposes all `/api/admin/*` endpoints behind `_check_admin(request, password)`:
+
+```python
+ADMIN_IP_ALLOWLIST    # comma-separated CIDRs or single IPs
+ADMIN_PASSWORD        # set via HF Space secret
+X-Admin-Password      # header on every admin request
+```
+
+Unauthorized callers get **HTTP 404 Not Found** (not 401) — the endpoints don't exist for them. This hides the admin surface from drive-by scanning.
+
+### UI surfacing
+
+The admin HTML (`frontend/public/admin/llm-control.html`) is iframe-embedded inside a new **"Admin · Access panel"** tab in the main app header, matching the existing tab pattern (Marketplace / Premium / Profile / Admin / Lang toggle). Same iframe, same backend; just a more discoverable entry point than typing the URL.
+
+## Alternatives considered
+
+| Auth method | Why rejected |
+|---|---|
+| Full OAuth (Google / GitHub) | Overkill for one operator; adds infra dependency. |
+| JWT with rotating keys | Doesn't add real security at this scale; rotation flow burdens operator. |
+| Single password, no IP gate | Password leak = anyone in the world owns the panel. |
+| IP gate only, no password | A neighbor on the same home network could probe. |
+
+| UI surfacing | Why rejected |
+|---|---|
+| Bookmark the URL | Loses on machine switches; no in-app discoverability. |
+| Native React rewrite of llm-control.html | Heavy lift; iframe gives full functionality immediately. |
+| Hidden keyboard shortcut | Operators forget shortcuts; worse than a visible button. |
+
+## Consequences
+
+**Positive:**
+
+- IP allowlist + password is a real security gate.
+- 404 (not 401) hides the endpoint's existence from non-allowlisted callers.
+- In-app tab is one-click for the operator; matches the other panel patterns.
+- iframe sandbox (`allow-scripts allow-same-origin allow-forms`) lets the panel call `/api/admin/*` cleanly.
+
+**Negative:**
+
+- Operator's IP changing (mobile network, café Wi-Fi, VPN) breaks access.
+- iframe pattern doesn't feel as native as a hand-coded React panel.
+
+**Mitigations:**
+
+- `ADMIN_IP_ALLOWLIST` is comma-separated → operator can add new IPs without code change.
+- Rotation is one command: `tools/set_hf_secrets.py` re-pushes `.env` to HF Space.
+- v2 can replace the iframe with a React panel using the same `/api/admin/*` endpoints — no backend change needed.
+
+## Revisit at scale
+
+- Replace IP gate with mutual-TLS or a real auth provider (Cloudflare Access, Tailscale ACL).
+- Native React admin panel for richer UX (live charts, alerting).

docs/60-decisions/ADR-024-triple-mirror-code-and-data.md

@@ -0,0 +1,81 @@
+# ADR-024: Triple-mirror — HuggingFace + GitHub + local for both code and data
+
+**Status:** Locked
+**Date:** 2026-05-14
+
+## Context
+
+The project's working state must be resilient against:
+
+1. **HF Space outage** — production deploy down.
+2. **HF Dataset corruption / accidental deletion** — entire RAG corpus lost.
+3. **Local Mac failure** — work-in-progress code lost.
+4. **GitHub repo nuked** — public mirror lost.
+
+Single-point-of-failure on any one layer is unacceptable.
+
+## Decision
+
+**Mirror both code and data across three layers.** Two GitHub repos parallel two HuggingFace artifacts.
+
+| Layer | Code | Data |
+|---|---|---|
+| **HuggingFace** | Space `rohitsar567/InsuranceBot` (Docker) | Dataset `rohitsar567/insurance-bot-data` |
+| **GitHub** | Repo `rohitsar567/insurance-sales-bot` | Repo `rohitsar567/insurance-sales-bot-data` (Git LFS) |
+| **Local Mac** | `~/Developer/Insurance Sales Bot/` working tree | `~/Developer/Insurance Sales Bot/rag/_hf_dataset_backup/` (gitignored) |
+
+## Alternatives considered
+
+| Mirror count | Why rejected |
+|---|---|
+| Single layer (HF only) | HF Space outage = product down + no backup of code state. |
+| Two layers (HF + local) | Local Mac failure or theft = irrecoverable. |
+| Two layers (HF + GitHub) | GitHub LFS bandwidth cap (1 GB/month free) is exposed to every external reviewer clone. |
+
+## Push fan-out pattern
+
+The code repo has two remotes:
+
+```
+origin → huggingface.co/spaces/rohitsar567/InsuranceBot (HF Space)
+github → github.com/rohitsar567/insurance-sales-bot
+```
+
+`git push origin main && git push github main` after every commit. Sync verification: `git rev-list --count main...origin/main` and same for `github/main`; both must equal 0.
+
+The data repo (`insurance-sales-bot-data`) on GitHub uses Git LFS for files >50 MB (the 157 MB chroma.sqlite3 and the 87 MB IRDAI master circular PDF).
+
+## End-user runtime path (important)
+
+External users hitting the live bot **never touch GitHub**. The runtime path is:
+
+```
+End user → HF Space (Docker container with data pre-baked at build time
+                     via snapshot_download from HF Dataset)
+```
+
+GitHub is for code mirror + offline backup. GitHub LFS bandwidth is only consumed by manual clones (operator on a new Mac, reviewer inspecting the repo).
+
+## Consequences
+
+**Positive:**
+
+- Three independent failure domains; any one outage doesn't lose the project.
+- Sarvam reviewers can inspect code on GitHub (the polished read-only surface).
+- HF reviewers can run the live demo.
+- Operator can rebuild the entire dataset from local backup if HF Dataset is ever lost.
+
+**Negative:**
+
+- Push fan-out is two commands instead of one.
+- Three sets of credentials (HF token, GitHub PAT, local file system).
+
+**Mitigations:**
+
+- A shell alias / git hook can collapse the dual push to one command if it becomes friction.
+- Tokens stored in `.git/config` (one-time setup per machine).
+
+## Revisit at scale
+
+- Add `git push origin main github main` as a single composite remote (`git remote add all` with two pushurls) so one command pushes to both.
+- For data, automate "HF Dataset commit → GitHub LFS sync" via a GitHub Action triggered by HF webhook.

docs/60-decisions/README.md

@@ -0,0 +1,46 @@
+# Architecture Decision Records (ADRs)
+
+Each major technical or product decision is captured as a single ADR using a lightly adapted Michael Nygard template: **Status · Context · Decision · Alternatives · Consequences · Revisit-at-scale**.
+
+ADR numbers map 1:1 to the original `D-NNN` entries that lived in the legacy `docs/decisions.md` (now split into individual files for easier review, citation, and supersession tracking).
+
+## Index
+
+| # | Title | Status |
+|---|---|---|
+| [ADR-001](ADR-001-vertical-slice-scope.md) | Vertical slice scope, not full platform | Locked |
+| [ADR-002](ADR-002-health-category-vertical.md) | Health as the v1 vertical category | Locked |
+| [ADR-003](ADR-003-curated-corpus.md) | Curated corpus over user-uploads | Locked |
+| [ADR-004](ADR-004-hybrid-structured-vector.md) | Hybrid structured + vector retrieval | Locked |
+| [ADR-005](ADR-005-nextjs-fastapi-frontend.md) | Next.js 14 + FastAPI (superseded original Streamlit pick) | Locked (revised) |
+| [ADR-006](ADR-006-sarvam-first-stack.md) | Sarvam-first STT/TTS/LLM defaults | Partially superseded by ADR-019 |
+| [ADR-007](ADR-007-illustrative-pricing.md) | Illustrative pricing, not real-time quotes | Locked |
+| [ADR-008](ADR-008-consultative-advisor-persona.md) | Consultative-advisor persona | Locked |
+| [ADR-009](ADR-009-19-insurer-comprehensive-schema.md) | 19 insurers × all health policies; 48-field schema | Locked |
+| [ADR-010](ADR-010-secret-handling.md) | Secret handling: `.env` chmod 600, gitignored | Locked |
+| [ADR-011](ADR-011-bge-local-embeddings.md) | Local BGE-small embeddings (Voyage was original) | Locked |
+| [ADR-012](ADR-012-render-then-hf-space-deploy.md) | Render → HF Space migration | Superseded |
+| [ADR-013](ADR-013-tailwind-shadcn-ui.md) | Tailwind CSS + shadcn/ui | Locked |
+| [ADR-014](ADR-014-groq-llama-grader.md) | Groq Llama-3.3-70B grader | Superseded by ADR-019 |
+| [ADR-015](ADR-015-openapi-typescript-codegen.md) | REST + `openapi-typescript` codegen | Locked |
+| [ADR-016](ADR-016-hybrid-brain-router.md) | Hybrid brain router (Sarvam + fallback) | Superseded by ADR-019 |
+| [ADR-017](ADR-017-irdai-corpus-playwright-rescue.md) | IRDAI regulatory corpus deferred → Playwright rescue | Locked |
+| [ADR-018](ADR-018-chunk-size-sweep-deferred.md) | Chunk-size sweep deferred; 800/120 baseline | Deferred to v2 |
+| [ADR-019](ADR-019-nim-single-provider-consolidation.md) | NVIDIA NIM as single non-Sarvam provider | Locked |
+| [ADR-020](ADR-020-code-data-split-hf-dataset.md) | Code in Space repo, data in companion HF Dataset | Locked |
+| [ADR-021](ADR-021-view-aware-system-prompt.md) | View-aware system prompt (D-020-frontend copilot) | Locked |
+| [ADR-022](ADR-022-conversational-profile-updates.md) | Conversational profile updates via LLM extractor | Locked |
+| [ADR-023](ADR-023-admin-panel-ip-gated.md) | Admin panel IP-gated; surfaced as in-app tab | Locked |
+| [ADR-024](ADR-024-triple-mirror-code-and-data.md) | Triple-mirror: HF + GitHub + local for both code and data | Locked |
+
+## How to add a new ADR
+
+1. Pick the next number (ADR-025).
+2. Copy the template from any existing ADR (Status / Context / Decision / Alternatives / Consequences / Revisit-at-scale).
+3. Status starts at `Proposed`; flip to `Locked` when implemented, `Superseded` when replaced.
+4. Add a row to this index.
+5. If superseding an older ADR, edit that ADR's status to `Superseded by ADR-NNN`.
+
+## Why split this from `decisions.md`?
+
+The legacy 32 KB `decisions.md` accumulated decisions chronologically. As the project grew, reviewers couldn't find the *current* state for a given concern without reading every entry in order. Per-decision files give each ADR a permanent URL, allow supersession tracking, and let new decisions land without merge conflicts in a giant monolithic file.