docs: update HLD/LLD to v0.3.0, add README, ADR 004-005

HLD: bump to v0.3.0, Phase 2 Complete, update roadmap table
LLD: add document_registry module, update chunker patterns,
add embedder truncation guard spec, update Neo4j stats to Phase 2
README: first version - quickstart, stack table, phase roadmap, ADR index
ADR 004: multi-format chunker (Act vs Rule boundary regex decision)
ADR 005: document registry as single source of truth

README.md

@@ -0,0 +1,159 @@
+# CivicSetu
+
+Open-source RAG system for querying Indian civic and legal documents — with accurate
+citations, cross-reference traversal, and conflict detection between laws.
+
+**Current status:** Phase 2 complete — RERA Act 2016 (Central) + Maharashtra Rules 2017.
+
+---
+
+## What it does
+
+Ask a plain-English question about RERA or Maharashtra real estate rules. Get a cited,
+structured answer with section references, confidence score, and a legal disclaimer.
+
+```
+
+Query: "What must a promoter disclose before selling a flat?"
+
+Answer: "Under Section 11(3) of RERA Act 2016, a promoter must disclose...
+Rule 3(2) of Maharashtra Rules further requires..."
+
+Citations: [Section 11, RERA Act 2016], [Rule 3(2), Maharashtra Rules 2017]
+Confidence: 0.95 (high)
+
+```
+
+---
+
+## Architecture
+
+```
+
+FastAPI → LangGraph Agent → pgvector + Neo4j + PostgreSQL
+↑
+Ingestion Pipeline (PDF → chunks → embeddings → graph)
+
+```
+
+Three stores per query:
+- **pgvector** — semantic similarity (fact lookups)
+- **Neo4j** — section graph traversal (cross-references, penalties)
+- **PostgreSQL** — full chunk text + metadata
+
+Full design: [HLD.md](docs/HLD.md) | [LLD.md](docs/LLD.md)
+
+---
+
+## Quickstart
+
+### Prerequisites
+
+- Docker + Docker Compose
+- [Ollama](https://ollama.ai) running locally
+- `uv` package manager
+
+### 1. Start infrastructure
+
+```bash
+docker compose up -d          # PostgreSQL + pgvector + Neo4j
+ollama pull nomic-embed-text  # embedding model
+```
+
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+# Set GEMINI_API_KEY (or GROQ_API_KEY for backup)
+# Neo4j and Postgres defaults work out of the box with Docker Compose
+```
+
+
+### 3. Install dependencies
+
+```bash
+uv sync
+```
+
+
+### 4. Ingest documents
+
+```bash
+uv run python scripts/ingest_phase0.py   # RERA Act 2016
+uv run python scripts/ingest_phase2.py   # Maharashtra Rules 2017
+```
+
+
+### 5. Run the API
+
+```bash
+uv run uvicorn civicsetu.api.main:app --reload
+```
+
+
+### 6. Query
+
+```bash
+curl -X POST http://localhost:8000/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What are the penalties for a promoter who delays possession?"}'
+```
+
+
+---
+
+## Documents ingested
+
+| Document | Jurisdiction | Chunks | Sections |
+| :-- | :-- | :-- | :-- |
+| RERA Act 2016 | Central | 224 | 92 |
+| Maharashtra Real Estate Rules 2017 | Maharashtra | 214 | 44 |
+
+
+---
+
+## Tech stack
+
+| Layer | Technology |
+| :-- | :-- |
+| API | FastAPI + Uvicorn |
+| Orchestration | LangGraph StateGraph |
+| LLM routing | LiteLLM (Gemini → Groq → OpenRouter) |
+| Embeddings | nomic-embed-text via Ollama (local) |
+| Vector DB | pgvector + HNSW index |
+| Graph DB | Neo4j Community |
+| Relational | PostgreSQL + SQLAlchemy |
+| Reranker | FlashRank (ms-marco-MiniLM-L-12-v2) |
+| PDF parsing | PyMuPDF |
+
+
+---
+
+## Phase roadmap
+
+| Phase | Scope | Status |
+| :-- | :-- | :-- |
+| 0 | RERA Act 2016, vector RAG, FastAPI | Complete |
+| 1 | Neo4j graph, cross-reference queries | Complete |
+| 2 | MahaRERA Rules 2017, multi-jurisdiction | Complete |
+| 3 | DERIVED_FROM edges, conflict detection | Next |
+| 4 | Multi-state expansion (UP, TN, Karnataka) | Planned |
+| 5 | Open-source SaaS, UI, public API | Planned |
+
+
+---
+
+## ADRs
+
+- [ADR 001 — three store architecture](docs/adr/001-three-store-architecture.md)
+- [ADR 002 — section boundary chunking](docs/adr/002-section-boundary-chunking.md)
+- [ADR 003 — LangGraph over LangChain chains](docs/adr/003-langgraph-over-langchain.md)
+- [ADR 004 — Multi-format chunker](docs/adr/004-multi-format-chunker.md)
+- [ADR 005 — Document registry](docs/adr/005-document-registry.md)
+
+
+## Disclaimer
+
+CivicSetu provides AI-generated legal information, not legal advice.
+Always verify with a qualified lawyer or the official gazette.

docs/HLD.md

@@ -1,8 +1,8 @@
 # CivicSetu — High Level Design (HLD)
 
-**Version:** 0.2.0 — Phase 1 Complete
+**Version:** 0.3.0 — Phase 2 Complete
 **Last Updated:** March 2026
-**Status:** Phase 1 Complete — Graph Retrieval Live
+**Status:** Phase 2 Complete — Multi-jurisdiction ingestion live
 
 ---
 
@@ -15,7 +15,7 @@ amendment tracking, and conflict detection between laws.
 **Target Users:** Indian citizens, lawyers, homebuyers, activists navigating RERA, RTI,
 labor law, GST compliance, and other civic frameworks.
 
-**Phase 0 Scope:** RERA Act 2016 (Central) — queryable via REST API.
+**Current Scope:** RERA Act 2016 (Central) + Maharashtra Real Estate Rules 2017.
 
 ---
 
@@ -27,28 +27,29 @@ labor law, GST compliance, and other civic frameworks.
 │                        CLIENT LAYER                              │
 │              HTTP REST (FastAPI) — /api/v1/query                 │
 └────────────────────────────┬─────────────────────────────────────┘
-│
+							 │
 ┌────────────────────────────▼─────────────────────────────────────┐
-│                     LANGGRAPH AGENT                               │
-│                                                                   │
+│                     LANGGRAPH AGENT                              │
+│                                                                  │
 │  [Classifier] → [Vector Retrieval] → [Reranker]                  │
-│       ↑               ↓ (Phase 1: + Graph Retrieval)             │
-│  [Retry]  ←  [Validator] ← [Generator]                          │
+│       ↑         [Graph Retrieval]  ↗                             │
+│  [Retry]  ←  [Validator] ← [Generator]                           │
 └────────────────────────────┬─────────────────────────────────────┘
-│
-┌────────────────────┼─────────────────────┐
-│                    │                      │
-┌───────▼──────┐   ┌─────────▼───────┐   ┌────────▼────────┐
-│  pgvector    │   │   Neo4j         │   │   PostgreSQL     │
-│  (vectors)   │   │  (graph)        │   │  (metadata)      │
-│  Phase 0 ✅  │   │  Phase 1 🔜     │   │  Phase 0 ✅      │
-└───────┬──────┘   └─────────┬───────┘   └────────┬────────┘
-│                    │                      │
-└────────────────────┴──────────────────────┘
-│
+							 │
+		  ┌──────────────────┼──────────────────────┐
+		  │                  │                      │
+  ┌───────▼──────┐   ┌───────▼─────────┐    ┌───────▼────────┐
+  │  pgvector    │   │   Neo4j         │    │   PostgreSQL   │
+  │  (vectors)   │   │   (graph)       │    │   (metadata)   │
+  │  Phase 0     │   │   Phase 1       │    │   Phase 0      │
+  └───────┬──────┘   └───────┬─────────┘    └───────┬────────┘
+          │                  │                      │
+          └──────────────────┴──────────────────────┘
+							 │
 ┌────────────────────────────▼─────────────────────────────────────┐
-│                    INGESTION PIPELINE                             │
+│                    INGESTION PIPELINE                            │
 │  Download → Parse → Chunk → Enrich → Embed → Store               │
+│  document_registry.py — single source of truth for all doc URLs  │
 └──────────────────────────────────────────────────────────────────┘
 
 ```
@@ -63,15 +64,15 @@ Runs once per document. Triggered via `make ingest` or `POST /api/v1/ingest`.
 
 ```
 
-PDF URL
-→ Downloader       (httpx, cached locally)
-→ PDFParser        (PyMuPDF, text extraction)
-�� LegalChunker     (section-boundary regex)
-→ MetadataExtractor(dates, references, amendment signals)
-→ Embedder         (nomic-embed-text via Ollama, local)
-→ RelationalStore  (PostgreSQL — documents + legal_chunks tables)
-→ VectorStore      (pgvector — HNSW index, cosine similarity)
-→ GraphStore       (Neo4j — Phase 1)
+PDF URL (from document_registry.py)
+→ Downloader        (httpx, cached locally with MD5 check)
+→ PDFParser         (PyMuPDF, text extraction, scanned page detection)
+→ LegalChunker      (multi-format regex: Act + Rule boundary detection)
+→ MetadataExtractor (dates, cross-references, amendment signals)
+→ Embedder          (nomic-embed-text via Ollama, MAX_EMBED_CHARS=6000 guard)
+→ RelationalStore   (PostgreSQL — documents + legal_chunks tables)
+→ VectorStore       (pgvector — HNSW index, cosine similarity)
+→ GraphStore        (Neo4j — Document + Section nodes + edges)
 
 ```
 
@@ -82,15 +83,15 @@ Triggered on every `POST /api/v1/query`.
 ```
 
 User Query
-→ Input Guardrails  (Phase 1)
+→ Input Guardrails  (PII + off-topic filter)
 → Classifier Node   (LLM — query_type + rewritten_query)
-→ Vector Retrieval  (pgvector cosine search, top_k chunks)
-→ Graph Retrieval   (Neo4j Cypher, REFERENCES traversal (bidirectional, depth=2))
-                    Fallback: vector retrieval when no section ID in query
+→ Vector Retrieval  (pgvector cosine search, top_k chunks)  ← fact_lookup
+→ Graph Retrieval   (Neo4j, REFERENCES traversal, depth=2)  ← cross_reference / penalty / temporal
+Fallback: vector retrieval when no section ID in query
 → Reranker          (FlashRank ms-marco-MiniLM-L-12-v2, cross-encoder)
 → Generator Node    (LLM — structured JSON answer with citations)
 → Validator Node    (LLM — hallucination + confidence check)
-→ Output Guardrails (Phase 1)
+→ Output Guardrails (faithfulness check + disclaimer injection)
 → CivicSetuResponse (answer + citations + confidence + disclaimer)
 
 ```
@@ -99,19 +100,20 @@ User Query
 
 ## 4. Component Responsibilities
 
-| Component | Responsibility | Technology |
-|---|---|---|
-| PDFParser | Text extraction from PDFs | PyMuPDF |
-| LegalChunker | Section-boundary splitting | Regex + fallback |
-| MetadataExtractor | Date, reference, amendment extraction | Regex |
-| Embedder | Dense vector generation | nomic-embed-text (Ollama) |
-| VectorStore | Semantic similarity search | pgvector + HNSW |
-| GraphStore | Section relationship traversal | Neo4j Community |
-| RelationalStore | Metadata persistence + chunk storage | PostgreSQL + SQLAlchemy |
-| LangGraph Agent | Query orchestration state machine | LangGraph |
-| LiteLLM Gateway | LLM provider fallback routing | LiteLLM |
-| FastAPI | HTTP API layer | FastAPI + Uvicorn |
-| FlashRank | Cross-encoder reranking | ONNX local model |
+| Component          | Responsibility                              | Technology                      |
+|--------------------|---------------------------------------------|---------------------------------|
+| DocumentRegistry   | Centralised doc URL + metadata management   | Python dataclass                |
+| PDFParser          | Text extraction from PDFs                   | PyMuPDF                         |
+| LegalChunker       | Multi-format section-boundary splitting     | Regex (Act + Rule patterns)     |
+| MetadataExtractor  | Date, reference, amendment extraction       | Regex                           |
+| Embedder           | Dense vector generation + truncation guard  | nomic-embed-text (Ollama)       |
+| VectorStore        | Semantic similarity search                  | pgvector + HNSW                 |
+| GraphStore         | Section relationship traversal              | Neo4j Community                 |
+| RelationalStore    | Metadata persistence + chunk storage        | PostgreSQL + SQLAlchemy         |
+| LangGraph Agent    | Query orchestration state machine           | LangGraph                       |
+| LiteLLM Gateway    | LLM provider fallback routing               | LiteLLM                         |
+| FastAPI            | HTTP API layer                              | FastAPI + Uvicorn               |
+| FlashRank          | Cross-encoder reranking                     | ONNX local model                |
 
 ---
 
@@ -141,7 +143,7 @@ Step 2  Graph       → traverse Section 18 node, incoming + outgoing REFERENCES
 Step 2b Fallback    → vector retrieval if graph returns 0 results
 Step 3  Rerank      → cross-encoder scores, top 5 ordered
 Step 4  Generate    → LLM produces JSON with answer + citations
-Step 5  Validate    → hallucination check, confidence score (skip retry if empty retrieval)
+Step 5  Validate    → hallucination check, confidence score
 Step 6  Respond     → CivicSetuResponse with citations + disclaimer
 
 Output: {
@@ -158,24 +160,23 @@ Output: {
 
 ## 7. Phase Roadmap
 
-| Phase | Scope                                          | Status              |
-|-------|------------------------------------------------|---------------------|
-| 0     | RERA Act 2016, vector RAG, FastAPI             | ✅ Complete         |
-| 1     | Neo4j graph, cross-reference queries           | ✅ Complete         |
-| 2     | MahaRERA Rules + Circulars, amendment tracking | 🔜 Next             |
-| 3     | Conflict detection, multi-document reasoning   | Planned             |
-| 4     | Multi-state expansion (UP, TN, Karnataka RERA) | Planned             |
-| 5     | Open-source SaaS, UI, public API               | Planned             |
-
+| Phase | Scope                                          | Status          |
+|-------|------------------------------------------------|-----------------|
+| 0     | RERA Act 2016, vector RAG, FastAPI             | ✅ Complete     |
+| 1     | Neo4j graph, cross-reference queries           | ✅ Complete     |
+| 2     | MahaRERA Rules 2017, multi-jurisdiction        | ✅ Complete     |
+| 3     | DERIVED_FROM edges, conflict detection         | Next            |
+| 4     | Multi-state expansion (UP, TN, Karnataka RERA) | Planned         |
+| 5     | Open-source SaaS, UI, public API               | Planned         |
 
 ---
 
 ## 8. Non-Functional Requirements
 
-| Requirement | Target | Current Status |
-|---|---|---|
-| Response latency | < 10s per query | ~5–8s (local embedding) |
-| Citation accuracy | 100% — never answer without citation | Enforced by schema |
-| Hallucination rate | < 5% | Validator node + confidence gate |
-| Cost | $0 for dev/staging | ✅ All free tier |
-| Portability | Runs on any machine with Docker | ✅ Docker Compose |
+| Requirement        | Target                               | Current Status                  |
+|--------------------|--------------------------------------|---------------------------------|
+| Response latency   | < 10s per query                      | ~5–8s (local embedding)         |
+| Citation accuracy  | 100% — never answer without citation | Enforced by schema              |
+| Hallucination rate | < 5%                                 | Validator node + confidence gate|
+| Cost               | $0 for dev/staging                   | All free tier                   |
+| Portability        | Runs on any machine with Docker      | Docker Compose                  |

docs/LLD.md

@@ -11,47 +11,48 @@
 
 src/civicsetu/
 ├── config/
-│   └── settings.py         Pydantic BaseSettings singleton (lru_cache)
+│   ├── settings.py           Pydantic BaseSettings singleton (lru_cache)
+│   └── document_registry.py  All document URLs + metadata (single source of truth)
 ├── models/
-│   ├── enums.py             StrEnum: Jurisdiction, DocType, QueryType, etc.
-│   └── schemas.py           Pydantic models: LegalChunk, Citation, CivicSetuResponse
+│   ├── enums.py              StrEnum: Jurisdiction, DocType, QueryType, etc.
+│   └── schemas.py            Pydantic models: LegalChunk, Citation, CivicSetuResponse
 ├── ingestion/
-│   ├── downloader.py        httpx PDF downloader with MD5 cache check
-│   ├── parser.py            PyMuPDF text extractor, scanned PDF detection
-│   ├── chunker.py           Section-boundary regex chunker + fallback
+│   ├── downloader.py         httpx PDF downloader with MD5 cache check
+│   ├── parser.py             PyMuPDF text extractor, scanned PDF detection
+│   ├── chunker.py            Section-boundary regex chunker + fallback
 │   ├── metadata_extractor.py Date/reference/amendment regex extraction
-│   ├── embedder.py          nomic-embed-text via Ollama (document + query prefixes)
-│   └── pipeline.py          Orchestrates all ingestion steps end-to-end
+│   ├── embedder.py           nomic-embed-text via Ollama (document + query prefixes)
+│   └── pipeline.py           Orchestrates all ingestion steps end-to-end
 ├── stores/
-│   ├── relational_store.py  Async SQLAlchemy — documents + legal_chunks tables
-│   ├── vector_store.py      pgvector HNSW cosine search
-│   └── graph_store.py       Neo4j Cypher interface (Phase 1)
+│   ├── relational_store.py   Async SQLAlchemy — documents + legal_chunks tables
+│   ├── vector_store.py       pgvector HNSW cosine search
+│   └── graph_store.py        Neo4j Cypher interface (Phase 1)
 ├── retrieval/
-│   ├── vector_retriever.py  Wraps VectorStore for agent use
-│   ├── graph_retriever.py   Cypher query builder (Phase 1)
-│   └── reranker.py          FlashRank cross-encoder wrapper
+│   ├── vector_retriever.py   Wraps VectorStore for agent use
+│   ├── graph_retriever.py    Cypher query builder (Phase 1)
+│   └── reranker.py           FlashRank cross-encoder wrapper
 ├── agent/
-│   ├── state.py             CivicSetuState TypedDict (frozen contract)
-│   ├── nodes.py             Pure functions: classifier, retrieval, reranker,
-│   │                        generator, validator
-│   ├── edges.py             Conditional routing: route_after_classifier,
-│   │                        route_after_validator
-│   └── graph.py             StateGraph assembly + get_compiled_graph()
+│   ├── state.py              CivicSetuState TypedDict (frozen contract)
+│   ├── nodes.py              Pure functions: classifier, retrieval, reranker,
+│   │                         generator, validator
+│   ├── edges.py              Conditional routing: route_after_classifier,
+│   │                         route_after_validator
+│   └── graph.py              StateGraph assembly + get_compiled_graph()
 ├── prompts/
-│   ├── classifier.py        Query type classification + rewriting prompt
-│   ├── generator.py         Cited answer generation prompt
-│   └── validator.py         Hallucination + confidence check prompt
+│   ├── classifier.py         Query type classification + rewriting prompt
+│   ├── generator.py          Cited answer generation prompt
+│   └── validator.py          Hallucination + confidence check prompt
 ├── guardrails/
-│   ├── input_guard.py       PII detection + off-topic filter (Phase 1)
-│   └── output_guard.py      Faithfulness check + disclaimer injection (Phase 1)
+│   ├── input_guard.py        PII detection + off-topic filter (Phase 1)
+│   └── output_guard.py       Faithfulness check + disclaimer injection (Phase 1)
 └── api/
-├── main.py              FastAPI app factory + lifespan (graph pre-compiled)
+├── main.py                   FastAPI app factory + lifespan (graph pre-compiled)
 ├── routes/
-│   ├── health.py        GET /health — DB ping
-│   ├── query.py         POST /api/v1/query — main RAG endpoint
-│   └── ingest.py        POST /api/v1/ingest — Phase 1 admin endpoint
+│   ├── health.py             GET /health — DB ping
+│   ├── query.py              POST /api/v1/query — main RAG endpoint
+│   └── ingest.py             POST /api/v1/ingest — Phase 1 admin endpoint
 └── middleware/
-└── logging.py       Request/response structured logging
+└── logging.py                Request/response structured logging
 
 ```
 
@@ -201,25 +202,35 @@ validator → route_after_validator:
 
 ### Section Boundary Detection
 
-Indian legal acts follow a consistent numbering format:
+Two regex patterns to cover both document formats ingested:
+
+**Act format** (RERA Act 2016):
 
 ```
+^\s*(?P<id>\d+[A-Z]?)\.?\s*(?P<title>[A-Z][^\n—]{3,80})\.?—
 ```
 
-^\s*(?P<id>\d+[A-Z]?)\.\s+(?P<title>[A-Za-z][^—\n]{3,80})\.?—
+Matches: `18. Return of amount and compensation.—`
+
+**Rule format** (MahaRERA Rules 2017):
 
 ```
+\n(?P<id>\d+)\.\s*\n(?P<title>[A-Z][^\n]{3,80})\n
 ```
 
-Matches: `1. Short title.—` / `18A. Special provisions.—` / ` 2. Definitions.—`
+Matches: `\n3.\nInformation to be furnished...\n`
+
+Chunker tries Act pattern first; falls back to Rule pattern; falls back to paragraph
+split if neither matches. Logs `chunking_fallback_used` on paragraph path.
 
 ### Chunk Size Limits
 
 ```
 MIN_CHARS = 100   — discard fragments (headers, page numbers)
-MAX_CHARS = 2000  — split large sections at subsection markers (1), (2), (a), (b)
+MAX_CHARS = 1500  — split large sections at subsection markers (1), (2), (a), (b)
 ```
 
+Reduced from 2000 → 1500 to stay within nomic-embed-text practical token window.
 
 ### Split Priority for Large Sections
 
@@ -253,6 +264,18 @@ Query time:      "search_query: {query}"     → embed_query()
 Using wrong prefix at query time causes ~10–15% recall degradation.
 The `embed_document()` / `embed_query()` method split enforces this at the API level.
 
+### Truncation Guard
+
+```python
+MAX_EMBED_CHARS = 6000   # ~1500 tokens for nomic-embed-text
+if len(text) > MAX_EMBED_CHARS:
+    log.warning("embedding_truncated", original_len=len(text), truncated_to=MAX_EMBED_CHARS)
+    text = text[:MAX_EMBED_CHARS]
+```
+
+Prevents silent API errors on oversized chunks. Expected to fire on 0–2 chunks per
+document where subsection splitting fails (complex tables, long definition lists).
+
 ---
 
 ## 6. Response Contract
@@ -316,3 +339,17 @@ If `citations` would be empty → return `InsufficientInfoResponse` instead.
 - Any query with explicit section number (e.g. "Section 18") → cross_reference
 - cross_reference + penalty_lookup + temporal → graph_retrieval node
 - fact_lookup + conflict_detection → vector_retrieval node
+
+## 8. Neo4j Graph — Phase 2 State
+
+**Nodes seeded:** 2 Documents, 438 Section nodes
+**Edges seeded:** 438 HAS_SECTION, 124 REFERENCES, 0 DERIVED_FROM (Phase 3)
+
+**Documents in graph:**
+- RERA Act 2016 (CENTRAL) — 224 sections, 63 REFERENCES edges
+- Maharashtra Real Estate Rules 2017 (MAHARASHTRA) — 214 sections, 61 REFERENCES edges
+
+**Known issue (Phase 3 backlog):**
+Citation deduplication keys on `section_id` only, not `(section_id, doc_name)`.
+Cross-doc queries may show duplicate section IDs from different documents.
+Fix: update generator citation dedup to composite key.

docs/adr/004-multi-format-chunker.md

@@ -0,0 +1,86 @@
+# ADR 004 — Multi-format Legal Document Chunker
+
+**Date:** March 2026
+**Status:** Accepted
+
+---
+
+## Context
+
+Phase 2 required ingesting Maharashtra Real Estate Rules 2017 alongside the RERA Act
+2016. Both are Indian legal PDFs but use structurally different numbering formats:
+
+**Act format (RERA Act 2016):**
+
+
+18. Return of amount and compensation.—
+(1) If the promoter fails to complete...
+
+Section title and em-dash are on the same line as the section number.
+
+**Rule format (Maharashtra Rules 2017):**
+
+
+3. 
+
+Information to be furnished by the promoter...
+
+
+Section number is on its own line, followed by a blank line, then the title.
+
+The existing Act-format regex (`^\s*\d+[A-Z]?\.\s+[A-Z][^—\n]{3,80}\.?—`) produces
+zero section boundaries on MahaRERA, triggering fallback paragraph chunking.
+Paragraph chunking on MahaRERA produces 80+ chunks with no section_id metadata —
+breaking citation accuracy entirely.
+
+## Decision
+
+Extend `LegalChunker` with a second boundary pattern for Rule format, applied as
+a sequential fallback:
+
+```python
+PATTERNS = [
+    ```
+    ("act",  r'^\s*(?P<id>\d+[A-Z]?)\.?\s*(?P<title>[A-Z][^\n—]{3,80})\.?—'),
+    ```
+    ```
+    ("rule", r'\n(?P<id>\d+)\.\s*\n(?P<title>[A-Z][^\n]{3,80})\n'),
+    ```
+]
+
+for name, pattern in PATTERNS:
+    matches = list(re.finditer(pattern, text, re.MULTILINE))
+    if len(matches) >= MIN_SECTIONS:
+        log.info("chunker_pattern_selected", pattern=name, sections=len(matches))
+        break
+```
+
+`MIN_SECTIONS = 5` — fewer than 5 matches is treated as noise, not real boundaries.
+
+The chunker logs which pattern was selected per document. Paragraph fallback is only
+reached if both patterns fail.
+
+## Consequences
+
+**Positive:**
+
+- MahaRERA produces 214 meaningful chunks with proper section_id metadata (44 sections)
+- Citation accuracy preserved — every chunk maps to an identifiable Rule number
+- Pattern selection is logged — observable, not silent
+- Adding a third pattern (e.g. circular format) requires one array entry
+
+**Negative:**
+
+- Pattern priority is implicit — if a document accidentally matches Rule pattern first
+with >= 5 hits, it bypasses Act pattern (mitigated by trying Act first)
+- Regex fragility: PDFs with unusual whitespace will still hit fallback
+
+
+## Alternatives Rejected
+
+- **Hardcode document type in ingestion config:** Requires caller to know format ahead
+of time; breaks the "any PDF URL" contract of the ingestion pipeline
+- **ML-based section detector:** Overkill for deterministic numbered formats; adds
+model dependency with no recall benefit on well-formatted government PDFs
+- **Single universal regex:** No single pattern can match both `18. Title.—` and
+`\n18.\n\nTitle\n` without catastrophic false positives

docs/adr/005-document-registry.md

@@ -0,0 +1,80 @@
+# ADR 005 — Document Registry as Single Source of Truth
+
+**Date:** March 2026
+**Status:** Accepted
+
+---
+
+## Context
+
+Phase 2 introduced a second document. With two documents, ingestion scripts started
+duplicating URL strings, jurisdiction values, and doc_name strings across:
+
+- `scripts/ingest_phase0.py`
+- `scripts/ingest_phase2.py`
+- Tests
+- Any future migration or re-ingestion scripts
+
+A URL change (e.g. NAREDCO moves their PDF) would require grep-and-replace across
+multiple files with no compile-time safety.
+
+## Decision
+
+Introduce `src/civicsetu/config/document_registry.py` as the single authoritative
+source for all document metadata:
+
+```python
+@dataclass(frozen=True)
+class DocumentSpec:
+    name: str
+    url: str
+    jurisdiction: Jurisdiction
+    doc_type: DocType
+    effective_date: date | None = None
+
+DOCUMENT_REGISTRY: dict[str, DocumentSpec] = {
+    "rera_act_2016": DocumentSpec(
+        name="RERA Act 2016",
+        url="https://...",
+        jurisdiction=Jurisdiction.CENTRAL,
+        doc_type=DocType.ACT,
+        effective_date=date(2016, 5, 26),
+    ),
+    "mahrera_rules_2017": DocumentSpec(
+        name="Maharashtra Real Estate (Regulation and Development) Rules 2017",
+        url="https://naredco.in/...",
+        jurisdiction=Jurisdiction.MAHARASHTRA,
+        doc_type=DocType.RULES,
+        effective_date=date(2017, 4, 21),
+    ),
+}
+```
+
+All ingestion scripts import from `document_registry`. No URL strings appear outside
+this file.
+
+## Consequences
+
+**Positive:**
+
+- URL change = one-line edit, guaranteed to propagate everywhere
+- `DocumentSpec` is a frozen dataclass — immutable, hashable, diffable in git
+- Phase 4 (multi-state expansion) is a registry append, not a script rewrite
+- Tests can iterate `DOCUMENT_REGISTRY.values()` for fixture generation
+
+**Negative:**
+
+- Adding a document requires a code change + deploy (not a DB insert)
+- Acceptable for Phase 0–3 volume (~10 documents); revisit for Phase 4+
+
+
+## Alternatives Rejected
+
+- **Database table for document registry:** Correct long-term, premature for current
+volume. Adds a DB round-trip to every ingestion bootstrap.
+- **Environment variables per document:** Unscalable beyond 2–3 documents;
+no structure, no type safety
+- **YAML/TOML config file:** Adds a parsing layer with no type safety; dataclass
+achieves the same with Python's own type checker
+
+