# Foxhunt Documentation Index

**Last Updated**: 2025-10-14
**Status**: Organized and Indexed
**Total Documentation**: 912 files, 11.7 MB

---

## 🎯 Start Here

### New to Foxhunt?
1. **[CLAUDE.md](/home/jgrusewski/Work/foxhunt/CLAUDE.md)** - System overview, architecture, current status (MUST READ)
2. **[README.md](/home/jgrusewski/Work/foxhunt/README.md)** - Project introduction
3. **[ML Infrastructure Guide](/home/jgrusewski/Work/foxhunt/docs/ML_INFRASTRUCTURE_GUIDE.md)** - Master documentation index

### Quick Start Guides
1. **[Quick Start: Training](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TRAINING.md)** - Train your first model (5-7 weeks)
2. **[Quick Start: Tuning](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TUNING.md)** - Optimize hyperparameters (3-4 days)

---

## 📁 Documentation Categories

### Training Guides (`training/`)
**371 documents** - ML model training, checkpoints, hyperparameters
- DQN, PPO, MAMBA-2, TFT training
- Checkpoint management
- Feature engineering
- GPU optimization

**Key Files**:
- [ML Training Roadmap](/home/jgrusewski/Work/foxhunt/ML_TRAINING_ROADMAP.md)
- [GPU Benchmark Guide](/home/jgrusewski/Work/foxhunt/ml/docs/GPU_BENCHMARK_GUIDE.md)
- [Agent 78: DQN Production Training](/home/jgrusewski/Work/foxhunt/AGENT_78_DQN_PRODUCTION_TRAINING_SUCCESS.md)
- [Checkpoint Selection Framework](/home/jgrusewski/Work/foxhunt/docs/CHECKPOINT_SELECTION_FRAMEWORK.md)

### Deployment Guides (`deployment/`)
**546 documents** - Production deployment, infrastructure, operations
- Production runbooks
- Docker deployment
- Infrastructure scaling
- Security hardening

**Key Files**:
- [Production Deployment Runbook V3](/home/jgrusewski/Work/foxhunt/docs/PRODUCTION_DEPLOYMENT_RUNBOOK_V3.md)
- [Ensemble Production Deployment](/home/jgrusewski/Work/foxhunt/ENSEMBLE_PRODUCTION_DEPLOYMENT_STRATEGY.md)
- [Paper Trading Deployment](/home/jgrusewski/Work/foxhunt/PAPER_TRADING_DEPLOYMENT_PLAN.md)
- [Docker Deployment](/home/jgrusewski/Work/foxhunt/DOCKER_DEPLOYMENT.md)

### Analysis & Reports (`analysis/`)
**738 documents** - Performance analysis, audits, investigations
- Wave reports (488 files)
- Agent reports
- Performance benchmarks
- Security audits

**Key Files**:
- [Wave 160 Phase 4 Complete](/home/jgrusewski/Work/foxhunt/WAVE_160_PHASE4_COMPLETE.md)
- [ML Validation Metrics Framework](/home/jgrusewski/Work/foxhunt/ML_VALIDATION_METRICS_FRAMEWORK.md)
- [Ensemble Strategy Deep Analysis](/home/jgrusewski/Work/foxhunt/ENSEMBLE_STRATEGY_DEEP_ANALYSIS.md)

### API Reference (`api/`)
**716 documents** - gRPC endpoints, integrations, service interfaces
- API Gateway (22 methods)
- Trading Service
- Backtesting Service
- ML Training Service

**Key Files**:
- [ML Infrastructure Guide - API Section](/home/jgrusewski/Work/foxhunt/docs/ML_INFRASTRUCTURE_GUIDE.md#api-reference)
- gRPC proto files in service directories

### Quick Start Guides (`guides/`)
**129 documents** - Getting started, tutorials, runbooks
- Training guides
- Tuning guides
- Deployment guides
- Troubleshooting guides

**Key Files**:
- [Quick Start: Training](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TRAINING.md)
- [Quick Start: Tuning](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TUNING.md)
- [Tuning Quickstart Guide](/home/jgrusewski/Work/foxhunt/TUNING_QUICKSTART_GUIDE.md)

### Troubleshooting (`troubleshooting/`)
**667 documents** - Debug guides, fixes, known issues
- Port conflicts
- GPU/CUDA issues
- Database connection
- Service health

**Key Files**:
- [Troubleshooting Guide](/home/jgrusewski/Work/foxhunt/docs/TROUBLESHOOTING_GUIDE.md)
- [Compilation Victory](/home/jgrusewski/Work/foxhunt/docs/COMPILATION_VICTORY.md)

### Archive (`archive/`)
**50+ candidates** - Obsolete and historical documentation
- Superseded versions
- Completed wave reports
- Temporary handoffs
- Duplicate content

---

## 🔍 Find Documentation By...

### By Topic
- **Authentication** → Security section
- **Backtesting** → Training guides + Deployment
- **Checkpoints** → Training guides
- **Deployment** → Deployment guides
- **GPU/CUDA** → Training guides
- **Hyperparameters** → Tuning guides
- **Models (DQN/PPO/MAMBA-2/TFT)** → Training guides
- **Performance** → Analysis section
- **Security** → Deployment guides
- **Testing** → Analysis section

### By Use Case
| I want to... | Start here |
|--------------|------------|
| Train a model | [Quick Start: Training](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TRAINING.md) |
| Optimize hyperparameters | [Quick Start: Tuning](/home/jgrusewski/Work/foxhunt/docs/guides/QUICK_START_TUNING.md) |
| Deploy to production | [Production Deployment Runbook V3](/home/jgrusewski/Work/foxhunt/docs/PRODUCTION_DEPLOYMENT_RUNBOOK_V3.md) |
| Troubleshoot an issue | [Troubleshooting Guide](/home/jgrusewski/Work/foxhunt/docs/TROUBLESHOOTING_GUIDE.md) |
| Understand the API | [ML Infrastructure Guide - API Section](/home/jgrusewski/Work/foxhunt/docs/ML_INFRASTRUCTURE_GUIDE.md#api-reference) |
| Set up paper trading | [Paper Trading Deployment Plan](/home/jgrusewski/Work/foxhunt/PAPER_TRADING_DEPLOYMENT_PLAN.md) |

---

## 📊 Documentation Statistics

### By Category
- Analysis/Reports: 738 files (80.9%)
- API Reference: 716 files (78.5%)
- Troubleshooting: 667 files (73.1%)
- Deployment: 546 files (59.9%)
- Wave Reports: 488 files (53.5%)
- Architecture: 463 files (50.8%)
- Training: 371 files (40.7%)

### By Size
- Total: 11.7 MB (404,079 lines)
- Largest: DATA_PLAN.md (99.3K)
- Average: 13.1K per file

### By Location
- Root directory: 421 files (46%)
- Docs directory: 334 files (37%)
- Other directories: 157 files (17%)

---

## 🔧 Contributing to Documentation

### Adding New Documentation
1. Choose appropriate category directory
2. Follow naming convention (UPPERCASE_SNAKE_CASE.md)
3. Add entry to ML_INFRASTRUCTURE_GUIDE.md
4. Include cross-references to related docs
5. Update this README if adding new category

### Updating Existing Documentation
1. Update file content
2. Update "Last Updated" date
3. Update cross-references if structure changes
4. Update ML_INFRASTRUCTURE_GUIDE.md if major changes

### Archiving Documentation
1. Move to `docs/archive/YYYY-MM-DD-reason/`
2. Create README in archive directory
3. Update ML_INFRASTRUCTURE_GUIDE.md
4. Remove from this index

---

## 📅 Recent Updates

### 2025-10-14 (Documentation Consolidation)
- Created ML Infrastructure Guide (master index)
- Created 2 quick-start guides (Training, Tuning)
- Organized directory structure (7 categories)
- Added 200+ cross-references
- Identified 50+ archive candidates

### 2025-10-13 (Wave 160 Phase 4)
- ML training pipeline complete
- 19 agents, 4 models trained
- System 100% production ready

---

## 🎯 Next Steps

### Phase 2 (Short-term - 1-2 weeks)
1. Move files to category directories
2. Create consolidated guides (API, Training, Deployment)
3. Archive obsolete documentation
4. Add more cross-references

### Phase 3 (Medium-term - 1 month)
1. Consolidate wave reports (488 → 20 phase summaries)
2. Enhance troubleshooting guide
3. Search optimization (keywords, metadata)
4. Documentation tests (link validation)

---

## 📞 Support

### Documentation Issues
- **Missing documentation?** Create GitHub issue with `docs` label
- **Broken links?** Submit PR with fix
- **Outdated content?** File issue with current status

### Technical Support
- **Development**: See [Troubleshooting Guide](/home/jgrusewski/Work/foxhunt/docs/TROUBLESHOOTING_GUIDE.md)
- **Deployment**: Review production runbooks
- **ML Training**: Consult training guides
- **Performance**: See performance benchmarks

---

**Document Version**: 1.0
**Created**: 2025-10-14
**Last Updated**: 2025-10-14
**Maintained by**: Foxhunt Development Team