Update README.md

README.md

@@ -1,152 +1,227 @@
 ---
-license: mit
-title: 'FOIA DECLASSIFIED DOCUMENTS SEARCH '
+title: Federal FOIA Intelligence Search
+emoji: 🏛️
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-colorFrom: purple
-colorTo: gray
+sdk_version: 4.44.1
+app_file: app.py
 pinned: true
+license: mit
 short_description: 'FOIA DECLASSIFIED DOCUMENTS SEARCH '
-sdk_version: 6.3.0
 ---
 
 # 🏛️ Federal FOIA Intelligence Search
-### Public Electronic Reading Rooms Only
 
-A **live federated search application** for discovering documents published in **public U.S. Government FOIA Electronic Reading Rooms**.
+**Public FOIA Electronic Reading Rooms • Link-Out Only • Court-Aware**
 
-This application **does not scrape**, **does not bypass access controls**, and **does not access classified, restricted, or non-public systems**.
+A Hugging Face–hosted research, journalism, and legal-support tool for discovering, organizing, and exporting **public U.S. government FOIA materials** from official electronic reading rooms.
+
+This application **does not scrape, host, or redistribute documents**.  
+All results are **direct links to official government FOIA libraries**.
 
 ---
 
-## 🔍 What This App Does
+## 🔍 Core Capabilities
+
+### ✔ Federated FOIA Search (LIVE)
+Search across multiple U.S. government FOIA libraries simultaneously.
 
-- 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
+**LIVE Agencies (Public & Safe):**
+- CIA — FOIA Electronic Reading Room  
+- FBI — The Vault  
+- DOJ — FOIA Library  
+- DHS — FOIA Reading Room  
+- State Department — FOIA Search  
+- GSA — FOIA Library  
+- NSA — FOIA Reading Room  
+
+All results link directly to official government sources.
 
 ---
 
-## 🛡️ Compliance & Safety Guarantees
+### 🧪 Extended Coverage (Clearly Labeled STUBS)
+Optional **non-exportable indicators** for agencies where automated access may be restricted or ambiguous.
+
+- DIA
+- NGA
+- NRO
+- TEN-CAP
+- AATIP
+- SAP / Special Activities
 
-- ✅ 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:**
+- ❌ No URLs
+- ❌ No exports
+- ❌ No PDFs
+- ❌ No citations
 
-> **Stub results are informational and cannot be exported.**
+This separation is a **deliberate compliance safeguard**.
 
 ---
 
-## 🧠 Search Modes
+### 📄 PDF Thumbnail Gallery
+For results that link directly to `.pdf` files:
 
-### Standard Mode (Default)
-- Live public FOIA reading rooms
-- Safe for export
-- No experimental features
+- Inline iframe preview (HF-safe)
+- Action buttons:
+  - **View**
+  - **Download**
+  - **Share** (device-native share API if supported)
+  - **Ask AI** (safe placeholder — no ingestion)
 
-### Extended Coverage Mode (Opt-In)
-Some agencies publish material inconsistently or restrict automation.
+> PDFs are never downloaded, cached, or stored by the app.
 
-Extended mode:
-- Requires user acknowledgment
-- Clearly labels blocked or stubbed agencies
-- Never exports restricted results
+---
 
-Agencies currently marked as **blocked or partial**:
-- DIA
-- NGA
+### 🗂 Journalist ZIP Export (LIVE Only)
+Generates a ZIP package for editorial or investigative workflows.
 
----
+**Contents:**
+- `README.txt` — scope & disclaimer
+- `citations.txt` — Bluebook-ready citations
+- `links.csv` — agency, title, URL, timestamp
+- `pdf_links.txt` — direct PDF URLs (no files)
+
+✔ Public sources only  
+✔ No redistribution  
+✔ No STUB data  
 
-## 🧾 Export Rules
+---
 
-- ZIP export is enabled **only when live results are present**
-- Stub results are excluded automatically
-- All exports are traceable to public URLs
+### 🌐 Public Shareable Result Pages
+Generate static, shareable result summaries containing:
+- Agency + title
+- Direct source links
+- Bluebook citations
+- Citation hash for integrity verification
 
 ---
 
-## 📊 Built-In Transparency Tools
+### ⚖️ Court-Aware Features
+Each LIVE result includes:
+- SHA-256 citation hash
+- Bluebook citation
+- Retrieval timestamp
 
-- 📊 **Agency coverage heatmap**
-- ⏱️ **Per-agency latency & health badges**
-- 🕒 **Release timeline (by publication date)**
-- 🌐 **Agency discovery status**
-- 🧾 **Court-ready citation formatting (public documents only)**
+Supports:
+- Litigation appendices
+- Exhibit preparation
+- Evidentiary traceability
 
 ---
 
-## ⚖️ Phase-3 Expansion Pack (Planned)
+### 🧠 Semantic Mode (Opt-In)
+- FAISS + SentenceTransformers (optional)
+- Metadata embeddings only
+- Disabled by default
+- Auto-disabled if dependencies unavailable
 
-These features are **architectural extensions** and are **not active by default**.
+---
+
+### 📊 Visual Analytics
+- Entity / domain frequency graphs
+- Retrieval timeline charts
 
-### 🧾 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
+### 📝 FOIA Request Generator
+Generate a fillable FOIA request PDF using:
+- Requester name
+- Description of records
+- Agencies surfaced in LIVE results
 
-### ⚖️ 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
+## 🧱 What This App Does NOT Do
 
-> No Phase-3 feature enables access to non-public data.
+❌ No scraping  
+❌ No crawling behind authentication  
+❌ No hosting or redistributing documents  
+❌ No classified access  
+❌ No private datasets  
+❌ No surveillance or tracking  
 
 ---
 
-## 📜 Why This Does Not Violate Intelligence Restrictions
+# 🛡️ TRUST & SAFETY ADDENDUM (HF REVIEWERS)
 
-- 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
+### Compliance Summary
+This Space is intentionally designed to comply with:
+- Hugging Face Spaces policies
+- U.S. FOIA public-access norms
+- Journalism ethics standards
 
----
+### Safety Controls
+- **Link-out only** (no content ingestion)
+- **Explicit STUB labeling**
+- **Export gating (LIVE-only)**
+- **No PDF storage**
+- **No background crawling**
+- **User-initiated queries only**
 
-## 🧪 Testing & Reliability
+### Risk Mitigation
+- No robots.txt violations (manual user navigation)
+- No automated retrieval of sensitive systems
+- No claims of completeness or authority
 
-- Adapter compliance tests ensure:
-  - Public access only
-  - Robots.txt compliance
-  - Required metadata fields
-- Health checks run without persistence or tracking
+This Space functions as a **research navigation and citation tool**, not a data collection system.
 
 ---
 
-## 🚀 Intended Users
+# ⚖️ LEGAL REVIEW MEMO (NON-BINDING)
+
+### Scope
+This application operates entirely within:
+- Public FOIA Electronic Reading Rooms
+- User-directed navigation
+
+### Key Legal Characteristics
+- No republication of copyrighted works
+- No derivative document creation
+- No alteration of government records
+- No implied agency endorsement
 
-- Journalists
-- Researchers
-- Attorneys
-- Transparency advocates
-- Members of the public
+### Litigation Safety
+- Citation hashes provide integrity verification
+- Source URLs remain authoritative
+- Export artifacts include disclaimers
+
+This tool supports lawful research and reporting, not legal conclusions.
 
 ---
 
-## 📌 Disclaimer
+# 📰 JOURNALIST ONBOARDING GUIDE
+
+### Typical Workflow
+1. Enter investigative topic
+2. Review LIVE agency coverage
+3. Examine PDF previews
+4. Export journalist ZIP
+5. Generate FOIA follow-up request
+6. Share result summary with editors
+
+### Best Practices
+- Always open documents at the source
+- Use citation hashes for verification
+- Treat STUB indicators as leads only
+- File FOIA requests directly with agencies
+
+### Ethical Use
+- Attribute sources accurately
+- Avoid implying classified access
+- Verify context before publication
+
+---
 
-This application is **not affiliated with any U.S. government agency**.  
-All documents remain the property of their originating agencies.
+## ⚠️ Disclaimer
+This tool:
+- Is not affiliated with any U.S. government agency
+- Does not guarantee completeness
+- Does not provide legal advice
 
 ---
 
-**Public transparency. Public sources. Clear boundaries.**
+**Built for transparency.  
+Designed for accountability.  
+Safe by construction.**