chore: improve DevEx and clean up obsolete docs (#25)

- Add `make all` as default target (alias for check)
- Add `make cov` as shorter alias for test-cov
- Add `make cov-html` for HTML coverage reports
- Update `make clean` to remove htmlcov/
- Remove obsolete docs/pending/ planning docs (all phases complete)
- Update docs/index.md with current status (Phases 1-14 complete)
- Fix broken doc links and update team section

Makefile

@@ -1,4 +1,7 @@
-.PHONY: install test lint format typecheck check clean
+.PHONY: install test lint format typecheck check clean all cov cov-html
+
+# Default target
+all: check
 
 install:
 	uv sync --all-extras
@@ -7,9 +10,15 @@ install:
 test:
 	uv run pytest tests/unit/ -v
 
+# Coverage aliases
+cov: test-cov
 test-cov:
 	uv run pytest --cov=src --cov-report=term-missing
 
+cov-html:
+	uv run pytest --cov=src --cov-report=html
+	@echo "Coverage report: open htmlcov/index.html"
+
 lint:
 	uv run ruff check src tests
 
@@ -23,5 +32,5 @@ check: lint typecheck test
 	@echo "All checks passed!"
 
 clean:
-	rm -rf .pytest_cache .mypy_cache .ruff_cache __pycache__ .coverage
+	rm -rf .pytest_cache .mypy_cache .ruff_cache __pycache__ .coverage htmlcov
 	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true

docs/index.md

@@ -9,10 +9,10 @@ AI-powered deep research system for accelerating drug repurposing discovery.
 ## Quick Links
 
 ### Architecture
-- **[Overview](architecture/overview.md)** - Project overview, use case, architecture, timeline
-- **[Design Patterns](architecture/design-patterns.md)** - 17 technical patterns, reference repos, judge prompts, data models
+- **[Overview](architecture/overview.md)** - Project overview, use case, architecture
+- **[Design Patterns](architecture/design-patterns.md)** - Technical patterns, data models
 
-### Implementation (Start Here!)
+### Implementation
 - **[Roadmap](implementation/roadmap.md)** - Phased execution plan with TDD
 - **[Phase 1: Foundation](implementation/01_phase_foundation.md)** ✅ - Tooling, config, first tests
 - **[Phase 2: Search](implementation/02_phase_search.md)** ✅ - PubMed search
@@ -22,18 +22,18 @@ AI-powered deep research system for accelerating drug repurposing discovery.
 - **[Phase 6: Embeddings](implementation/06_phase_embeddings.md)** ✅ - Semantic search + dedup
 - **[Phase 7: Hypothesis](implementation/07_phase_hypothesis.md)** ✅ - Mechanistic reasoning
 - **[Phase 8: Report](implementation/08_phase_report.md)** ✅ - Structured scientific reports
-- **[Phase 9: Source Cleanup](implementation/09_phase_source_cleanup.md)** 📝 - Remove DuckDuckGo
-- **[Phase 10: ClinicalTrials](implementation/10_phase_clinicaltrials.md)** 📝 - Clinical trials API
-- **[Phase 11: bioRxiv](implementation/11_phase_biorxiv.md)** 📝 - Preprint search
+- **[Phase 9: Source Cleanup](implementation/09_phase_source_cleanup.md)** ✅ - Remove DuckDuckGo
+- **[Phase 10: ClinicalTrials](implementation/10_phase_clinicaltrials.md)** ✅ - Clinical trials API
+- **[Phase 11: bioRxiv](implementation/11_phase_biorxiv.md)** ✅ - Preprint search
+- **[Phase 12: MCP Server](implementation/12_phase_mcp_server.md)** ✅ - Claude Desktop integration
+- **[Phase 13: Modal Integration](implementation/13_phase_modal_integration.md)** ✅ - Secure code execution
+- **[Phase 14: Demo Submission](implementation/14_phase_demo_submission.md)** ✅ - Hackathon submission
 
 ### Guides
-- [Setup Guide](guides/setup.md) (coming soon)
 - **[Deployment Guide](guides/deployment.md)** - Gradio, MCP, and Modal launch steps
 
 ### Development
 - **[Testing Strategy](development/testing.md)** - Unit, Integration, and E2E testing patterns
-- [Contributing](development/contributing.md) (coming soon)
-
 
 ---
 
@@ -54,7 +54,7 @@ AI-powered deep research system for accelerating drug repurposing discovery.
 User Question → Research Agent (Orchestrator)
                       ↓
               Search Loop:
-                → Tools (PubMed, Web Search)
+                → Tools (PubMed, ClinicalTrials, bioRxiv)
                 → Judge (Quality + Budget)
                 → Repeat or Synthesize
                       ↓
@@ -63,21 +63,22 @@ User Question → Research Agent (Orchestrator)
 
 ---
 
-## Hackathon Tracks
+## Features
 
-| Track | Status | Key Feature |
-|-------|--------|-------------|
-| **Gradio** | ✅ Planned | Streaming UI with progress |
-| **MCP** | ✅ Planned | PubMed as MCP server |
-| **Modal** | 🔄 Stretch | GPU inference option |
+| Feature | Status | Description |
+|---------|--------|-------------|
+| **Gradio UI** | ✅ Complete | Streaming chat interface |
+| **MCP Server** | ✅ Complete | Tools accessible from Claude Desktop |
+| **Modal Sandbox** | ✅ Complete | Secure statistical analysis |
+| **Multi-Source Search** | ✅ Complete | PubMed, ClinicalTrials, bioRxiv |
 
 ---
 
 ## Team
 
-- Physician (medical domain expert) ✅
-- Software engineers ✅
-- AI architecture validated by multiple agents ✅
+- The-Obstacle-Is-The-Way
+- MarioAderman
+- Josephrp
 
 ---
 
@@ -85,11 +86,7 @@ User Question → Research Agent (Orchestrator)
 
 | Phase | Status |
 |-------|--------|
-| Phases 1-8 | ✅ COMPLETE |
-| Phase 9: Remove DuckDuckGo | 📝 SPEC READY |
-| Phase 10: ClinicalTrials.gov | 📝 SPEC READY |
-| Phase 11: bioRxiv | 📝 SPEC READY |
+| Phases 1-14 | ✅ COMPLETE |
 
+**Test Coverage**: 65% (96 tests passing)
 **Architecture Review**: PASSED (98-99/100)
-**Phases 1-8**: COMPLETE
-**Next**: Phases 9-11 (Multi-Source Enhancement)

docs/pending/00_priority_summary.md

@@ -1,111 +0,0 @@
-# DeepCritical Hackathon Priority Summary
-
-## 4 Days Left (Deadline: Nov 30, 2025 11:59 PM UTC)
-
----
-
-## Git Contribution Analysis
-
-```text
-The-Obstacle-Is-The-Way: 20+ commits (Phases 1-11, all demos, all fixes)
-MarioAderman:            3 commits (Modal, LlamaIndex, PubMed fix)
-JJ (Maintainer):         0 code commits (merge button only)
-```
-
-**Conclusion:** You built 90%+ of this codebase.
-
----
-
-## Current Stack (What We Have)
-
-| Component | Status | Files |
-|-----------|--------|-------|
-| PubMed Search | ✅ Working | `src/tools/pubmed.py` |
-| ClinicalTrials Search | ✅ Working | `src/tools/clinicaltrials.py` |
-| bioRxiv Search | ✅ Working | `src/tools/biorxiv.py` |
-| Search Handler | ✅ Working | `src/tools/search_handler.py` |
-| Embeddings/ChromaDB | ✅ Working | `src/services/embeddings.py` |
-| LlamaIndex RAG | ✅ Working | `src/services/llamaindex_rag.py` |
-| Hypothesis Agent | ✅ Working | `src/agents/hypothesis_agent.py` |
-| Report Agent | ✅ Working | `src/agents/report_agent.py` |
-| Judge Agent | ✅ Working | `src/agents/judge_agent.py` |
-| Orchestrator | ✅ Working | `src/orchestrator.py` |
-| Gradio UI | ✅ Working | `src/app.py` |
-| Modal Code Execution | ⚠️ Built, not wired | `src/tools/code_execution.py` |
-| **MCP Server** | ✅ **Working** | `src/mcp_tools.py`, `src/app.py` |
-
----
-
-## What's Required for Track 2 (MCP in Action)
-
-| Requirement | Have It? | Priority |
-|-------------|----------|----------|
-| Autonomous agent behavior | ✅ Yes | - |
-| Must use MCP servers as tools | ✅ **YES** | Done (Phase 12) |
-| Must be Gradio app | ✅ Yes | - |
-| Planning/reasoning/execution | ✅ Yes | - |
-
-**Bottom Line:** ✅ MCP server implemented in Phase 12. Track 2 compliant.
-
----
-
-## 3 Things To Do (In Order)
-
-### 1. MCP Server (P0 - Required) ✅ DONE
-
-- **Files:** `src/mcp_tools.py`, `src/app.py`
-- **Status:** Implemented in Phase 12
-- **Doc:** `02_mcp_server_integration.md`
-- **Endpoint:** `/gradio_api/mcp/`
-
-### 2. Modal Wiring (P1 - $2,500 Prize)
-- **File:** Update `src/agents/analysis_agent.py`
-- **Time:** 2-3 hours
-- **Doc:** `03_modal_integration.md`
-- **Why:** Modal Innovation Award is $2,500
-
-### 3. Demo Video + Submission (P0 - Required)
-- **Time:** 1-2 hours
-- **Why:** Required for all submissions
-
----
-
-## Submission Checklist
-
-- [ ] Space in MCP-1st-Birthday org
-- [ ] Tag: `mcp-in-action-track-enterprise`
-- [ ] Social media post link
-- [ ] Demo video (1-5 min)
-- [ ] MCP server working
-- [ ] All tests passing
-
----
-
-## Prize Math
-
-| Award | Amount | Eligible? |
-|-------|--------|-----------|
-| Track 2 1st Place | $2,500 | If MCP works |
-| Modal Innovation | $2,500 | If Modal wired |
-| LlamaIndex | $1,000 | Yes (have it) |
-| Community Choice | $1,000 | Maybe |
-| **Total Potential** | **$7,000** | With MCP + Modal |
-
----
-
-## Next Actions
-
-```bash
-# 1. MCP Server - DONE ✅
-uv run python src/app.py  # Starts Gradio with MCP at /gradio_api/mcp/
-
-# 2. Test MCP works
-curl http://localhost:7860/gradio_api/mcp/schema | jq
-
-# 3. Wire Modal into pipeline
-# (see 03_modal_integration.md)
-
-# 4. Record demo video
-
-# 5. Submit to MCP-1st-Birthday org
-```

docs/pending/01_hackathon_requirements.md

@@ -1,99 +0,0 @@
-# MCP's 1st Birthday Hackathon - Requirements Analysis
-
-> **✅ MCP Server implemented in Phase 12** - Track 2 compliant
-
-## Deadline: November 30, 2025 11:59 PM UTC
-
----
-
-## Track Selection: MCP in Action (Track 2)
-
-DeepCritical fits **Track 2: MCP in Action** - AI agent applications.
-
-### Required Tags (pick one)
-```yaml
-tags:
-  - mcp-in-action-track-enterprise   # Drug repurposing = enterprise/healthcare
-  # OR
-  - mcp-in-action-track-consumer     # If targeting patients/consumers
-```
-
-### Track 2 Requirements
-
-| Requirement | DeepCritical Status | Action Needed |
-|-------------|---------------------|---------------|
-| Autonomous Agent behavior | ✅ Have it | Search-Judge-Synthesize loop |
-| Must use MCP servers as tools | ✅ **DONE** | `src/mcp_tools.py` |
-| Must be a Gradio app | ✅ Have it | `src/app.py` |
-| Planning, reasoning, execution | ✅ Have it | Orchestrator + Judge |
-| Context Engineering / RAG | ✅ Have it | LlamaIndex + ChromaDB |
-
----
-
-## Prize Opportunities
-
-### Current Eligibility vs With MCP Integration
-
-| Award | Prize | Current | With MCP |
-|-------|-------|---------|----------|
-| MCP in Action (1st) | $2,500 | ✅ Eligible | ✅ STRONGER |
-| Modal Innovation | $2,500 | ❌ Not using | ✅ ELIGIBLE (code execution) |
-| Blaxel Choice | $2,500 | ❌ Not using | ⚠️ Could integrate |
-| LlamaIndex | $1,000 | ✅ Using (Mario's code) | ✅ ELIGIBLE |
-| Google Gemini | $10K credits | ❌ Not using | ⚠️ Could add |
-| Community Choice | $1,000 | ⚠️ Possible | ✅ Better demo helps |
-| **TOTAL POTENTIAL** | | ~$2,500 | **$8,500+** |
-
----
-
-## Submission Checklist
-
-- [ ] HuggingFace Space in `MCP-1st-Birthday` organization
-- [ ] Track tags in Space README.md
-- [ ] Social media post link (X, LinkedIn)
-- [ ] Demo video (1-5 minutes)
-- [ ] All team members registered
-- [ ] Original work (Nov 14-30)
-
----
-
-## Priority Integration Order
-
-### P0 - MUST HAVE (Required for Track 2)
-1. **MCP Server Wrapper** - Expose search tools as MCP servers
-   - See: `02_mcp_server_integration.md`
-
-### P1 - HIGH VALUE ($2,500 each)
-2. **Modal Integration** - Already have code, need to wire up
-   - See: `03_modal_integration.md`
-
-### P2 - NICE TO HAVE
-3. **Blaxel** - MCP hosting platform (if time permits)
-4. **Gemini API** - Add as LLM option for Google prize
-
----
-
-## What MCP Actually Means for Us
-
-MCP (Model Context Protocol) is Anthropic's standard for connecting AI to tools.
-
-**Current state:**
-- We have `PubMedTool`, `ClinicalTrialsTool`, `BioRxivTool`
-- They're Python classes with `search()` methods
-
-**What we need:**
-- Wrap these as MCP servers
-- So Claude Desktop, Cursor, or any MCP client can use them
-
-**Why this matters:**
-- Judges will test if our tools work with Claude Desktop
-- No MCP = disqualified from Track 2
-
----
-
-## Reference Links
-
-- [Hackathon Page](https://huggingface.co/MCP-1st-Birthday)
-- [MCP Documentation](https://modelcontextprotocol.io/)
-- [Gradio MCP Guide](https://www.gradio.app/guides/building-mcp-server-with-gradio)
-- [Discord: #agents-mcp-hackathon-winter25](https://discord.gg/huggingface)

docs/pending/02_mcp_server_integration.md

@@ -1,177 +0,0 @@
-# MCP Server Integration
-
-## Priority: P0 - REQUIRED FOR TRACK 2
-
-> **✅ STATUS: IMPLEMENTED** - See `src/mcp_tools.py` and `src/app.py`
-> MCP endpoint: `/gradio_api/mcp/`
-
----
-
-## What We Need
-
-Expose our search tools as MCP servers so Claude Desktop/Cursor can use them.
-
-### Current Tools to Expose
-
-| Tool | File | MCP Tool Name |
-|------|------|---------------|
-| PubMed Search | `src/tools/pubmed.py` | `search_pubmed` |
-| ClinicalTrials Search | `src/tools/clinicaltrials.py` | `search_clinical_trials` |
-| bioRxiv Search | `src/tools/biorxiv.py` | `search_biorxiv` |
-| Combined Search | `src/tools/search_handler.py` | `search_all_sources` |
-
----
-
-## Implementation Options
-
-### Option 1: Gradio MCP (Recommended)
-
-Gradio 5.0+ can expose any Gradio app as an MCP server automatically.
-
-```python
-# src/mcp_server.py
-import gradio as gr
-from src.tools.pubmed import PubMedTool
-from src.tools.clinicaltrials import ClinicalTrialsTool
-from src.tools.biorxiv import BioRxivTool
-
-pubmed = PubMedTool()
-trials = ClinicalTrialsTool()
-biorxiv = BioRxivTool()
-
-async def search_pubmed(query: str, max_results: int = 10) -> str:
-    """Search PubMed for biomedical literature."""
-    results = await pubmed.search(query, max_results)
-    return "\n\n".join([f"**{e.citation.title}**\n{e.content}" for e in results])
-
-async def search_clinical_trials(query: str, max_results: int = 10) -> str:
-    """Search ClinicalTrials.gov for clinical trial data."""
-    results = await trials.search(query, max_results)
-    return "\n\n".join([f"**{e.citation.title}**\n{e.content}" for e in results])
-
-async def search_biorxiv(query: str, max_results: int = 10) -> str:
-    """Search bioRxiv/medRxiv for preprints."""
-    results = await biorxiv.search(query, max_results)
-    return "\n\n".join([f"**{e.citation.title}**\n{e.content}" for e in results])
-
-# Create Gradio interface
-demo = gr.Interface(
-    fn=[search_pubmed, search_clinical_trials, search_biorxiv],
-    inputs=[gr.Textbox(label="Query"), gr.Number(label="Max Results", value=10)],
-    outputs=gr.Textbox(label="Results"),
-)
-
-# Launch as MCP server
-if __name__ == "__main__":
-    demo.launch(mcp_server=True)  # Gradio 5.0+ feature
-```
-
-### Option 2: Native MCP SDK
-
-Use the official MCP Python SDK:
-
-```bash
-uv add mcp
-```
-
-```python
-# src/mcp_server.py
-from mcp.server import Server
-from mcp.types import Tool, TextContent
-
-from src.tools.pubmed import PubMedTool
-from src.tools.clinicaltrials import ClinicalTrialsTool
-from src.tools.biorxiv import BioRxivTool
-
-server = Server("deepcritical-research")
-
-@server.tool()
-async def search_pubmed(query: str, max_results: int = 10) -> list[TextContent]:
-    """Search PubMed for biomedical literature on drug repurposing."""
-    tool = PubMedTool()
-    results = await tool.search(query, max_results)
-    return [TextContent(type="text", text=e.content) for e in results]
-
-@server.tool()
-async def search_clinical_trials(query: str, max_results: int = 10) -> list[TextContent]:
-    """Search ClinicalTrials.gov for clinical trials."""
-    tool = ClinicalTrialsTool()
-    results = await tool.search(query, max_results)
-    return [TextContent(type="text", text=e.content) for e in results]
-
-@server.tool()
-async def search_biorxiv(query: str, max_results: int = 10) -> list[TextContent]:
-    """Search bioRxiv/medRxiv for preprints (not peer-reviewed)."""
-    tool = BioRxivTool()
-    results = await tool.search(query, max_results)
-    return [TextContent(type="text", text=e.content) for e in results]
-
-if __name__ == "__main__":
-    server.run()
-```
-
----
-
-## Claude Desktop Configuration
-
-After implementing, users add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "deepcritical": {
-      "command": "uv",
-      "args": ["run", "python", "src/mcp_server.py"],
-      "cwd": "/path/to/DeepCritical-1"
-    }
-  }
-}
-```
-
----
-
-## Testing MCP Server
-
-1. Start the MCP server (via Gradio app):
-
-```bash
-uv run python src/app.py
-```
-
-2. Check MCP schema:
-
-```bash
-curl http://localhost:7860/gradio_api/mcp/schema | jq
-```
-
-3. Test with MCP Inspector:
-
-```bash
-npx @anthropic/mcp-inspector http://localhost:7860/gradio_api/mcp/sse
-```
-
-4. Verify tools appear and work
-
----
-
-## Demo Video Script
-
-For the hackathon submission video:
-
-1. Show Claude Desktop with DeepCritical MCP tools
-2. Ask: "Search PubMed for metformin Alzheimer's"
-3. Show real results appearing
-4. Ask: "Now search clinical trials for the same"
-5. Show combined analysis
-
-This proves MCP integration works.
-
----
-
-## Files Created
-
-- [x] `src/mcp_tools.py` - MCP tool wrapper functions
-- [x] `src/app.py` - Gradio app with `mcp_server=True`
-- [x] `tests/unit/test_mcp_tools.py` - Unit tests
-- [x] `tests/integration/test_mcp_tools_live.py` - Integration tests
-- [x] `README.md` - Updated with MCP usage instructions

docs/pending/03_modal_integration.md

@@ -1,158 +0,0 @@
-# Modal Integration
-
-## Priority: P1 - HIGH VALUE ($2,500 Modal Innovation Award)
-
----
-
-## What Modal Is For
-
-Modal provides serverless GPU/CPU compute. For DeepCritical:
-
-### Current Use Case (Mario's Code)
-- `src/tools/code_execution.py` - Run LLM-generated analysis code in sandboxes
-- Scientific computing (pandas, scipy, numpy) in isolated containers
-
-### Potential Additional Use Cases
-
-| Use Case | Benefit | Complexity |
-|----------|---------|------------|
-| Code Execution Sandbox | Run statistical analysis safely | ✅ Already built |
-| LLM Inference | Run local models (no API costs) | Medium |
-| Batch Processing | Process many papers in parallel | Medium |
-| Embedding Generation | GPU-accelerated embeddings | Low |
-
----
-
-## Current State
-
-Mario implemented `src/tools/code_execution.py`:
-
-```python
-# Already exists - ModalCodeExecutor
-executor = get_code_executor()
-result = executor.execute("""
-import pandas as pd
-import numpy as np
-# LLM-generated statistical analysis
-""")
-```
-
-### What's Missing
-
-1. **Not wired into the main pipeline** - The executor exists but isn't used
-2. **No Modal tokens configured** - Needs MODAL_TOKEN_ID/MODAL_TOKEN_SECRET
-3. **No demo showing it works** - Judges need to see it
-
----
-
-## Integration Plan
-
-### Step 1: Wire Into Agent Pipeline
-
-Add a `StatisticalAnalyzer` service that uses Modal:
-
-```python
-# src/services/statistical_analyzer.py
-import asyncio
-from src.tools.code_execution import get_code_executor
-
-class StatisticalAnalyzer:
-    """Run statistical analysis on evidence using Modal sandbox."""
-
-    async def analyze(self, evidence: list[Evidence], query: str) -> str:
-        # 1. LLM generates analysis code
-        code = await self._generate_analysis_code(evidence, query)
-
-        # 2. Execute in Modal sandbox (run sync executor in thread pool)
-        executor = get_code_executor()
-        loop = asyncio.get_event_loop()
-        result = await loop.run_in_executor(None, executor.execute, code)
-
-        # 3. Return results
-        return result["stdout"]
-```
-
-### Step 2: Add to Orchestrator
-
-```python
-# In orchestrator, after gathering evidence:
-if settings.enable_modal_analysis:
-    analysis_agent = AnalysisAgent()
-    stats_results = await analysis_agent.analyze(evidence, query)
-```
-
-### Step 3: Create Demo
-
-```python
-# examples/modal_demo/run_analysis.py
-"""Demo: Modal-powered statistical analysis of drug evidence."""
-
-# Show:
-# 1. Gather evidence from PubMed
-# 2. Generate analysis code with LLM
-# 3. Execute in Modal sandbox
-# 4. Return statistical insights
-```
-
----
-
-## Modal Setup
-
-### 1. Install Modal CLI
-```bash
-pip install modal
-modal setup  # Authenticates with Modal
-```
-
-### 2. Set Environment Variables
-```bash
-# In .env
-MODAL_TOKEN_ID=your-token-id
-MODAL_TOKEN_SECRET=your-token-secret
-```
-
-### 3. Deploy (Optional)
-```bash
-modal deploy src/tools/code_execution.py
-```
-
----
-
-## What to Show Judges
-
-For the Modal Innovation Award ($2,500):
-
-1. **Sandbox Isolation** - Code runs in container, not local
-2. **Scientific Computing** - Real pandas/scipy analysis
-3. **Safety** - Can't access local filesystem
-4. **Speed** - Modal's fast cold starts
-
-### Demo Script
-
-```bash
-# Run the Modal verification script
-uv run python examples/modal_demo/verify_sandbox.py
-```
-
-This proves code runs in Modal, not locally.
-
----
-
-## Files to Update
-
-- [ ] Wire `code_execution.py` into pipeline
-- [ ] Create `src/agents/analysis_agent.py`
-- [ ] Update `examples/modal_demo/` with working demo
-- [ ] Add Modal setup to README
-- [ ] Test with real Modal account
-
----
-
-## Cost Estimate
-
-Modal pricing for our use case:
-- CPU sandbox: ~$0.0001 per execution
-- For demo/judging: < $1 total
-- Free tier: 30 hours/month
-
-Not a cost concern.