docs: professional README with full feature documentation

README.md

@@ -10,55 +10,199 @@ pinned: false
 license: mit
 ---
 
+<div align="center">
+
 # 🩺 EBP Research Tool for Student Nurses
 
-An **Evidence-Based Practice** research assistant built for nursing students.
-Search PubMed and ClinicalTrials.gov, get nursing-focused summaries, and
-generate APA 7th or AMA citations — all for free.
+**Evidence-Based Practice research, summarised and cited — in seconds**
+
+[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Live%20Demo-blue)](https://huggingface.co/spaces/NurseCitizenDeveloper/nursing-ebp-tool)
+[![GitHub](https://img.shields.io/badge/GitHub-Clinical--Quality--AI-181717?logo=github)](https://github.com/Clinical-Quality-Artifical-Intelligence/nursing-ebp-tool)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Data: PubMed](https://img.shields.io/badge/Data-PubMed%2030M%2B-blue)](https://pubmed.ncbi.nlm.nih.gov/)
+[![Data: ClinicalTrials](https://img.shields.io/badge/Data-ClinicalTrials.gov-blue)](https://clinicaltrials.gov/)
+
+*No login · No API key · No cost · Built by a nurse, for nurses*
+
+</div>
+
+---
+
+## Overview
+
+The **EBP Research Tool** connects student nurses directly to the world's largest biomedical databases — PubMed and ClinicalTrials.gov — and returns results as structured, nursing-focused summary cards complete with auto-graded evidence levels and paste-ready citations.
+
+Designed for nursing assignments, clinical rotation preparation, and NCLEX study, this tool removes the friction from evidence-based practice: no institutional access required, no complex database syntax to learn, and no manual citation formatting.
+
+---
 
 ## Features
 
-| Feature | Detail |
-|---------|--------|
-| 🔍 Multi-database search | PubMed (30M+ articles) · ClinicalTrials.gov |
-| 🧠 Nursing summary cards | Background · Methods · Key Findings · Nursing Implications |
-| 📊 Evidence level grading | Melnyk & Fineout-Overholt hierarchy (Levels I–VII) |
-| 📝 Citation generator | APA 7th edition · AMA — paste-ready |
-| 💾 Personal library | Save and export articles across your session |
-| ⚡ Quick-topic shortcuts | Wound care, pain management, fall prevention, and more |
+### 🔍 Multi-Database Search
+- **PubMed** — 30 million+ peer-reviewed biomedical articles (NCBI / NIH)
+- **ClinicalTrials.gov** — completed and active clinical studies
+- Filter by **publication date**, **study design**, and **nursing focus**
+- 8 pre-loaded quick-topic buttons for the most common nursing EBP areas
+
+### 🔬 Advanced Search Filters
+
+| Filter | Options |
+|--------|---------|
+| Database | PubMed · ClinicalTrials.gov · Both |
+| Date range | Last 1 year · 2 years · 5 years · 10 years · All time |
+| Study design | Systematic Review · Meta-Analysis · RCT · Cohort · Case Study · Any |
+| Nursing focus | Toggle to limit results to nursing-indexed content |
+
+### 🧠 Nursing Summary Cards
+Each article is parsed into a structured nursing-focused card:
+
+| Section | Content |
+|---------|---------|
+| **Overview / Background** | Study context and rationale |
+| **Methods** | Study design and participant information |
+| **Key Findings** | Primary results and outcomes |
+| **Nursing Implications** | Actionable points for clinical practice |
+
+### 📊 Evidence Level Grading
+Articles are automatically graded using the **Melnyk & Fineout-Overholt Evidence Hierarchy** — the standard framework used in nursing education:
+
+| Level | Study Type | Indicator |
+|-------|-----------|-----------|
+| Level I | Systematic Review / Meta-Analysis | 🟢 |
+| Level II | Randomised Controlled Trial (RCT) | 🟡 |
+| Level III | Quasi-Experimental Study | 🟠 |
+| Level IV | Cohort / Case-Control Study | 🟠 |
+| Level V | Systematic Review of Qualitative Studies | 🔵 |
+| Level VI | Qualitative / Descriptive Study | 🔵 |
+| Level VII | Expert Opinion / Consensus | ⚫ |
+
+### 📝 Citation Generator
+- **APA 7th Edition** — the standard for nursing and allied health programs
+- **AMA format** — for medical/clinical journal submissions
+- Paste-ready output with correct italics and DOI formatting
+- Lookup any article by PMID in the Citation Builder tab
+
+### 💾 Personal Library
+- Save articles during your session
+- Export all saved citations at once (APA 7th)
+- Full article cards available for each saved item
+
+---
+
+## Quick Topics
+
+Pre-loaded search shortcuts for the most common nursing EBP topics:
+
+| Topic | Topic |
+|-------|-------|
+| Wound Care | Pain Management |
+| Fall Prevention | Medication Safety |
+| Infection Control | Patient Education |
+| Mental Health | Paediatric Care |
+
+---
 
 ## Tech Stack
 
-- **Frontend:** Streamlit (Python)
-- **Data:** NCBI E-utilities API (PubMed) · ClinicalTrials.gov API v2
-- **Summarisation:** Heuristic structured-abstract parser (no GPU needed)
-- **Hosting:** Hugging Face Spaces — free CPU tier
+| Layer | Technology |
+|-------|-----------|
+| Frontend | [Streamlit](https://streamlit.io/) (Python) |
+| Literature search | [NCBI E-utilities](https://www.ncbi.nlm.nih.gov/books/NBK25497/) (PubMed) |
+| Clinical trials | [ClinicalTrials.gov API v2](https://clinicaltrials.gov/data-api/api) |
+| Summarisation | Heuristic structured-abstract parser (no GPU / no LLM required) |
+| Citation formatting | Custom APA 7th & AMA formatter |
+| Hosting | [Hugging Face Spaces](https://huggingface.co/spaces) — free CPU tier |
+| CI/CD | GitHub Actions → auto-deploy on push |
+
+> **No API keys required. No paid services. Fully open-source.**
+
+---
 
 ## Local Development
 
 ```bash
-git clone https://github.com/<your-org>/nursing-ebp-tool
+# Clone the repository
+git clone https://github.com/Clinical-Quality-Artifical-Intelligence/nursing-ebp-tool.git
 cd nursing-ebp-tool
+
+# Install dependencies
 pip install -r requirements.txt
-streamlit run app.py
+
+# Run the app
+streamlit run streamlit_app.py
+```
+
+Requirements: Python 3.10+ · `streamlit` · `requests`
+
+---
+
+## Deployment
+
+This app is deployed on **Hugging Face Spaces** and auto-deploys via GitHub Actions on every push to `main`.
+
+```
+git push origin main
+    → GitHub Actions triggers
+        → pushes to Hugging Face Spaces
+            → app rebuilds & goes live
 ```
 
-## Deployment (Hugging Face Spaces)
+To deploy your own instance:
+1. Fork this repository
+2. Create a Hugging Face Space (Streamlit SDK)
+3. Add your `HF_TOKEN` as a GitHub Actions secret
+4. Push to `main`
 
-1. Create a new Space → choose **Streamlit** SDK
-2. Connect your GitHub repo
-3. HF will auto-deploy on every push to `main`
+---
 
 ## Data Sources
 
-- **PubMed / NCBI** — public API, no key required (NCBI E-utilities)
-- **ClinicalTrials.gov** — public API v2, no key required
+| Source | Description | Articles / Records | Update Frequency |
+|--------|-------------|-------------------|-----------------|
+| [PubMed / NCBI](https://pubmed.ncbi.nlm.nih.gov/) | Biomedical literature database (NIH) | 30M+ | Daily |
+| [ClinicalTrials.gov](https://clinicaltrials.gov/) | U.S. and international clinical studies | 470K+ | Daily |
+
+All data is publicly available from U.S. government APIs — no institutional subscription required.
+
+---
+
+## About — Nursing Citizen Development
+
+This tool is part of the **Nursing Citizen Development** initiative — the idea that clinicians with domain expertise can build the software their profession needs, without waiting for a technology company to solve the problem.
+
+Built by a nurse. Designed for nurses.
+
+**Related tools:**
+- [Drug Card Generator](https://huggingface.co/spaces/NurseCitizenDeveloper/nursing-drug-cards) — Instant FDA drug reference cards with nursing considerations
+
+---
 
 ## Disclaimer
 
-This tool is for educational purposes only. Always verify information against
-original peer-reviewed sources before applying it in clinical practice.
+This tool is intended for **educational purposes only**. Search results are drawn from publicly available biomedical databases and may not represent the complete body of evidence on any given topic.
+
+Always appraise sources critically and verify information against your institutional resources, clinical guidelines, and supervisor guidance before applying evidence to clinical practice. This tool does not constitute clinical or professional advice.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
+
+Areas where help is appreciated:
+- Additional nursing topic shortcuts
+- Integration with Cochrane Library
+- Enhanced evidence level classification
+- Multilingual support
+
+---
 
 ## License
 
-MIT
+[MIT](LICENSE) © Nursing Citizen Development / Clinical Quality Artificial Intelligence
+
+---
+
+<div align="center">
+  <sub>Built with 🩺 by <a href="https://huggingface.co/NurseCitizenDeveloper">Nursing Citizen Development</a></sub>
+</div>