Update README.md

README.md

@@ -1,62 +1,151 @@
+---
+license: mit
+title: 'FOIA DECLASSIFIED DOCUMENTS SEARCH '
+sdk: gradio
+colorFrom: purple
+colorTo: gray
+pinned: true
+short_description: 'FOIA DECLASSIFIED DOCUMENTS SEARCH '
+---
+
 # 🏛️ Federal FOIA Intelligence Search
 ### Public Electronic Reading Rooms Only
 
-This Hugging Face Space provides **live search access to U.S. Government FOIA documents**
-released through official public Electronic Reading Rooms.
+A **live federated search application** for discovering documents published in **public U.S. Government FOIA Electronic Reading Rooms**.
+
+This application **does not scrape**, **does not bypass access controls**, and **does not access classified, restricted, or non-public systems**.
 
 ---
 
-## ✅ What This App Does
-- Searches **public FOIA portals** (e.g. FBI Vault, CIA Reading Room)
-- Clearly labels **Live vs Stub** results
-- Allows export **only** for lawfully retrievable documents
-- Requires explicit consent for extended (blocked) agencies
+## 🔍 What This App Does
+
+- Searches **publicly available FOIA libraries**
+- Aggregates results across multiple agencies
+- Clearly distinguishes:
+  - 🟢 **Live public sources**
+  - 🔒 **Stub / informational coverage**
+- Provides transparency tooling for journalists, researchers, and the public
 
 ---
 
-## 🔒 Stub Results (Transparency Only)
+## 🛡️ Compliance & Safety Guarantees
+
+- ✅ Public Electronic Reading Rooms only  
+- ✅ Honors robots.txt per adapter  
+- ✅ No authentication, credentials, or scraping  
+- ✅ No training, inference, or ML on restricted data  
+- ✅ Stub results **cannot be exported**  
+- ✅ All exported documents link to public URLs  
+
+> **Stub results are informational and cannot be exported.**
+
+---
 
-Some agencies do **not** permit automated access or do not provide public FOIA search endpoints.
+## 🧠 Search Modes
 
-These are represented as **stub adapters**:
-- NSA
+### Standard Mode (Default)
+- Live public FOIA reading rooms
+- Safe for export
+- No experimental features
+
+### Extended Coverage Mode (Opt-In)
+Some agencies publish material inconsistently or restrict automation.
+
+Extended mode:
+- Requires user acknowledgment
+- Clearly labels blocked or stubbed agencies
+- Never exports restricted results
+
+Agencies currently marked as **blocked or partial**:
+- DIA
 - NGA
-- (Others may be added similarly)
 
-Stub results:
-- ❌ Do not perform network requests
-- ❌ Do not retrieve documents
-- ❌ Cannot be exported
+---
+
+## 🧾 Export Rules
 
-> ℹ️ Stub results are informational and cannot be exported.
+- ZIP export is enabled **only when live results are present**
+- Stub results are excluded automatically
+- All exports are traceable to public URLs
 
 ---
 
-## 📤 Export Rules
-Only results from **live public FOIA sources** are exportable.
+## 📊 Built-In Transparency Tools
+
+- 📊 **Agency coverage heatmap**
+- ⏱️ **Per-agency latency & health badges**
+- 🕒 **Release timeline (by publication date)**
+- 🌐 **Agency discovery status**
+- 🧾 **Court-ready citation formatting (public documents only)**
 
 ---
 
-## 🧠 Ethics & Compliance
-- No classified systems accessed
-- No bypassing robots.txt
-- No scraping restricted endpoints
-- No personal data collected
-- Public FOIA releases only
+## ⚖️ Phase-3 Expansion Pack (Planned)
+
+These features are **architectural extensions** and are **not active by default**.
+
+### 🧾 Court Tools
+- Litigation appendix generator (PDF)
+- Exhibit numbering (A-1, A-2…)
+- Declaration-ready citation blocks
+- FOIA exemption (b-code) frequency charts
+
+### 📰 Journalism Tools
+- Timeline narrative builder
+- Source confidence tags
+- “What’s missing” agency gap analysis
+- Redaction density metrics
+
+### ⚖️ Compliance Controls
+- Export locked to live results only
+- Every document traceable to public URL
+- Stub data never enters PDFs
+- Optional disclosure watermarking
+
+### 🧠 Advanced (Opt-In)
+- Semantic clustering by topic (post-retrieval only)
+- Cross-agency entity graphs
+- FOIA response-time benchmarking
+
+> No Phase-3 feature enables access to non-public data.
+
+---
+
+## 📜 Why This Does Not Violate Intelligence Restrictions
+
+- The app queries **only public-facing FOIA libraries**
+- No inference is performed on classified material
+- No automation targets restricted systems
+- All content is already published by the agencies themselves
+- The app functions as a **search index**, not a data broker
+
+---
+
+## 🧪 Testing & Reliability
+
+- Adapter compliance tests ensure:
+  - Public access only
+  - Robots.txt compliance
+  - Required metadata fields
+- Health checks run without persistence or tracking
+
+---
+
+## 🚀 Intended Users
+
+- Journalists
+- Researchers
+- Attorneys
+- Transparency advocates
+- Members of the public
 
 ---
 
-## ✅ FINAL HF REVIEWER RESPONSE
+## 📌 Disclaimer
 
-> This Space performs automated searches only against U.S. Government FOIA Electronic Reading Rooms that explicitly permit public access.
->
-> Agencies that block automated access or lack public search endpoints are represented with clearly labeled stub results for transparency only.
->
-> Stub adapters do not perform network requests and cannot export content.
->
-> This application indexes only documents lawfully released to the public under FOIA.
+This application is **not affiliated with any U.S. government agency**.  
+All documents remain the property of their originating agencies.
 
 ---
 
-## 📜 Intended Use
-Research, journalism, transparency, and educational use only.
+**Public transparency. Public sources. Clear boundaries.**