Update README.md

README.md

@@ -12,99 +12,289 @@ short_description: 'FOIA DECLASSIFIED DOCUMENTS SEARCH '
 ---
 
 # 🏛️ Federal FOIA Intelligence Search
+### Public Electronic Reading Rooms · Evidence-Grade Citations · Responsible AI
 
-**Public FOIA Electronic Reading Rooms — Link-Out Search Only**
+---
+
+## Executive Summary
+
+**Federal FOIA Intelligence Search** is a **read-only, transparency-first research application** designed to help users **discover, organize, cite, and export publicly released U.S. government records** from official **FOIA Electronic Reading Rooms**.
+
+This application is intentionally built to meet:
+
+- 📰 Investigative journalism standards  
+- ⚖️ Legal evidentiary and citation expectations  
+- 🧠 Responsible AI principles  
+- 🛡️ Hugging Face Trust & Safety requirements  
+
+At all times, the system prioritizes **public accountability, verifiability, and user control** over automation or opaque data processing.
+
+---
+
+## Core Principles
+
+1. **Public Records Only**
+2. **Link-Out, Not Scraping**
+3. **User-Initiated Actions Only**
+4. **Explicit AI Opt-In**
+5. **Court-Ready Outputs**
+6. **Zero Background Data Collection**
+
+---
+
+## Supported Federal Agencies (Link-Out Only)
+
+The app generates **official search links** to the following FOIA Electronic Reading Rooms:
+
+- CIA — Central Intelligence Agency  
+- FBI — Federal Bureau of Investigation  
+- DOJ — Department of Justice  
+- DHS — Department of Homeland Security  
+- U.S. Department of State  
+- GSA — General Services Administration  
+- NSA — National Security Agency  
+
+> ⚠️ **Important:**  
+> This application **does not scrape, crawl, mirror, or store** documents from any agency.  
+> Each result redirects the user to the **agency’s official FOIA website**.
+
+---
+
+## How the App Works (Detailed)
+
+### Step 1 — User Search
+The user enters a search term in the unified FOIA search bar.
+
+### Step 2 — Federated Link Generation
+For each supported agency, the app:
+- Generates an agency-specific FOIA search URL
+- Measures request latency (for transparency)
+- Produces structured metadata (agency, URL, timestamp)
+
+### Step 3 — Results Presentation
+Results are displayed in two formats:
+- A structured data table
+- A polished card-based results gallery
+
+No documents are downloaded automatically.
+
+### Step 4 — Optional Actions
+Users may then:
+- View or download documents from the agency website
+- Generate citations, appendices, and exports
+- Explicitly opt-in to AI analysis
+
+---
+
+## Feature Overview
+
+### 🔍 Polished FOIA Search Interface
+
+- Unified search bar across agencies
+- Clear agency attribution
+- Latency badges for transparency
+- No hidden background requests
+
+---
+
+### 📚 Exhibit-Aware Bluebook Citations
+
+Each FOIA result is assigned:
+- A cryptographic citation hash
+- A sequential Exhibit ID (A-1, A-2, etc.)
+- A Bluebook-formatted citation
+
+**Designed for:**
+- Court filings
+- Academic papers
+- Investigative reporting
+- FOIA compliance audits
+
+---
+
+### ⚖️ Litigation Appendix & Table of Authorities (PDF)
+
+Generates a court-ready PDF containing:
+- Title page
+- Generation timestamp
+- Sequential exhibit list
+- Full Bluebook citations
+- Implicit Table of Authorities
+
+> 📌 The appendix contains **no AI-generated facts** — citations only.
 
-This Hugging Face Space provides a **federated discovery interface** for official U.S. Government Freedom of Information Act (FOIA) Electronic Reading Rooms.
+---
+
+### 📝 FOIA Request Generator
+
+Provides **ready-to-edit FOIA request drafts** that:
+- Reference the selected agency
+- Include the user’s topic
+- Follow standard FOIA request conventions
+
+> ⚠️ Templates must be reviewed and customized before submission.
+
+---
+
+### 🧠 AI Analysis (Strictly Opt-In)
+
+AI features are **disabled by default**.
+
+To enable AI, the user must explicitly:
+1. Enable AI analysis
+2. (Optionally) allow PDF text extraction
+
+AI analysis includes:
+- Source attribution
+- Context boundaries
+- Mandatory disclosure block
+- Cryptographic integrity hash
 
-⚠️ **This application does not scrape, crawl, mirror, store, or redistribute documents.**  
-All results link directly to authoritative government sources.
+---
+
+### 🔎 AI Citation Cross-Checking
+
+When AI is enabled:
+- All analysis is tied to a selected FOIA record
+- Unsupported claims are prevented
+- Missing citation context is flagged
+
+This reduces hallucinations and misuse.
 
 ---
 
-## 🎯 Purpose
+### 📊 Analytical Visualizations
+
+Available visual tools:
+- Agency Coverage Heatmap
+- Domain / Entity Frequency Graph
+- Timeline of FOIA publication dates
 
-- Accelerate public-interest research
-- Support journalism, litigation prep, and academic inquiry
-- Provide court-ready citations and documentation workflows
-- Enable **explicitly gated AI analysis** for public documents
+These operate **only on metadata**, not document contents.
 
 ---
 
-## ✔️ Core Guarantees
+### 🗂 Journalist & Reviewer Export Bundles
 
-- ��� **Link-out only** to official FOIA libraries  
-- 📄 **No document hosting or redistribution**  
-- 🧾 **Bluebook-formatted citations**  
-- 🧠 **AI analysis is explicit opt-in**  
-- ⚖️ **LIVE results only are exportable**  
-- 🚫 **STUB coverage is informational only**  
+One-click ZIP export containing:
+- `citations.txt` — Bluebook citations
+- `links.csv` — structured dataset
+- Shareable evidence bundle
 
 ---
 
-## 🏛️ Live FOIA Sources
+### 📤 Share Pages (Metadata Only)
 
-| Agency | Official Source |
-|------|----------------|
-| CIA | cia.gov/readingroom |
-| FBI | vault.fbi.gov |
-| DOJ | justice.gov/foia |
-| DHS | dhs.gov/foia |
-| State Dept | foia.state.gov |
-| GSA | gsa.gov |
-| NSA | nsa.gov |
+Users may generate a temporary Share ID that:
+- Preserves citation metadata
+- Never hosts documents
+- Exists only in memory
 
 ---
 
-## 🧠 AI & Semantic Features (Opt-In)
+## AI Disclosure & Integrity
 
-AI functionality is **disabled by default**.
+Every AI output includes:
 
-When enabled by the user:
-- PDFs are processed **only when explicitly selected**
-- AI analysis is **user-initiated**
-- Outputs include:
-  - Disclosure footer
-  - Integrity hash
-  - Source citation
-- AI output **is not a primary source** and **not legal advice**
+- Explicit disclosure notice
+- User-initiated confirmation
+- Integrity hash for auditability
 
-Optional FAISS semantic indexing operates on **metadata only** unless PDF analysis is explicitly requested.
+AI outputs are **not evidence** and **not legal advice**.
 
 ---
 
-## 🗂️ Exports & Research Tools
+## Privacy & Security
 
-- 🧾 Bluebook citations
-- 📦 Journalist ZIP (links + citations only)
-- 📄 FOIA request generator (PDF)
-- 🏛️ Litigation appendix generator
-- 📊 Entity graphs & timelines
+- No accounts
+- No cookies
+- No analytics
+- No persistent storage
+- In-memory session state only
 
 ---
 
-## 🔐 Trust & Safety
+## Warnings & Disclaimers ⚠️
 
-- No scraping or crawling
-- No robots.txt bypass
-- No credentialed systems
-- No personal data collection
-- Stateless execution
+### Not Legal Advice
+This application does not provide legal advice.
 
-See:
-- `TRUST_SAFETY.md`
-- `LEGAL_MEMO.md`
+### Not Evidence
+AI summaries are not admissible evidence.
+
+### Public Records Only
+The app cannot access unreleased, classified, or restricted materials.
+
+### No Government Affiliation
+This project is independent and not affiliated with any U.S. government entity.
 
 ---
 
-## 🚀 Deployment
+## Tips & Best Practices
 
-Designed for **Hugging Face Spaces (Gradio)**  
-No API keys required.
+- ✅ Always verify citations at the source
+- ✅ Use appendices for formal submissions
+- ✅ Treat AI as a research assistant, not an authority
+- ❌ Do not submit AI text as sworn testimony
+- ❌ Do not assume FOIA completeness
 
 ---
 
-## 📜 Disclaimer
+## Known Limitations
+
+- No full-text indexing
+- PDF extraction may fail on scanned documents
+- Latency reflects link generation only
+
+---
+
+## Considerations for Responsible Use
+
+- FOIA records may be incomplete or redacted
+- Agencies publish at different cadences
+- Absence of evidence is not evidence of absence
+
+---
+
+## Hugging Face Trust & Safety Alignment
+
+This Space:
+- Does not scrape or crawl
+- Does not bypass authentication
+- Does not host sensitive data
+- Does not train on user input
+- Does not automate surveillance
+
+All AI functionality is:
+- User-controlled
+- Transparent
+- Auditable
+
+---
+
+## Future & Planned Expansions (Non-Operational)
+
+Potential future enhancements may include:
+- Additional federal agencies
+- State-level FOIA reading rooms
+- Advanced citation validation
+- Redaction comparison tools
+- FOIA release trend analysis
+- Multi-appendix case bundling
+
+All future features will maintain:
+- Public-only access
+- Explicit user consent
+- Responsible AI design
+
+---
+
+## Final Note
+
+This application was built with a single guiding principle:
+
+> **Transparency without automation abuse. Evidence without distortion. AI only when invited.**
+
+---
 
-This tool assists discovery and analysis of public records.  
-Always verify information against the original government source.
+🏛️ **Public Records. Verified Sources. Responsible Intelligence.**