# Documentation Index

Complete documentation for the MEV Bot project.

## Quick Start

```bash
# 1. Start development environment
./scripts/dev.sh up

# 2. Build and test
./scripts/dev.sh build
./scripts/dev.sh test all

# 3. Run audit before commit
./scripts/dev.sh audit
./scripts/dev.sh check-compliance
```

## Core Documentation

### 📋 [SPEC.md](../SPEC.md)
**Technical Specification**

The authoritative technical specification for the entire project.

**Covers:**
- Architecture principles (channel-based, sequencer-first)
- Sequencer processing pipeline (4 stages)
- Contract bindings management
- Pool cache design
- Validation rules
- Critical DO/DON'T requirements

**Read this first** to understand project requirements.

---

### 📚 [CLAUDE.md](../CLAUDE.md)
**Development Guidelines**

Day-to-day development practices and project status.

**Covers:**
- Current project status
- Containerized development workflow
- Recent fixes and known issues
- Repository structure
- Git workflow
- Common development tasks

**Read this** for practical development guidance.

---

## Setup and Configuration

### 🔧 [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md)
**Environment Setup Guide**

Complete guide for setting up the development environment.

**Covers:**
- Quick start workflow
- Container-based development
- Contract development process
- Binding generation
- Directory structure
- Common tasks
- Troubleshooting

**Follow this** when setting up your dev environment.

---

## Testing and Quality

### 🧪 [AUDIT_AND_TESTING.md](AUDIT_AND_TESTING.md)
**Testing Guide**

Comprehensive testing and auditing procedures.

**Covers:**
- Unit tests
- Integration tests
- Race detection
- Benchmarks
- Coverage reports
- Code quality audits
- Security checks
- Documentation coverage
- SPEC.md compliance

**Use this** to ensure code quality.

---

### 📜 [SCRIPTS_REFERENCE.md](SCRIPTS_REFERENCE.md)
**Scripts Reference**

Complete reference for all development scripts.

**Covers:**
- `dev.sh` - Main development script
- `test.sh` - Testing suite
- `audit.sh` - Code audit
- `check-docs.sh` - Documentation coverage
- `check-compliance.sh` - SPEC.md compliance
- Contract scripts
- Utility scripts

**Reference this** when using development tools.

---

## Planning Documents

Located in `planning/` directory:

- `00_V2_MASTER_PLAN.md` - Complete V2 architecture
- `01_MODULARITY_REQUIREMENTS.md` - Modularity guidelines
- `07_TASK_BREAKDOWN.md` - Detailed task breakdown (~99 hours)

---

## By Use Case

### I want to...

#### Start Development
1. Read [SPEC.md](../SPEC.md) - Understand requirements
2. Follow [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md) - Set up environment
3. Read [CLAUDE.md](../CLAUDE.md) - Learn workflow

#### Write Code
1. Check [SPEC.md](../SPEC.md) - Verify requirements
2. Use [CLAUDE.md](../CLAUDE.md) - Follow practices
3. Run `./scripts/dev.sh build` - Build in container

#### Test Code
1. Read [AUDIT_AND_TESTING.md](AUDIT_AND_TESTING.md) - Learn testing
2. Run `./scripts/dev.sh test all` - Run all tests
3. Run `./scripts/dev.sh test coverage` - Check coverage

#### Audit Code
1. Run `./scripts/dev.sh audit` - Code quality audit
2. Run `./scripts/dev.sh check-compliance` - SPEC.md compliance
3. Run `./scripts/dev.sh check-docs` - Documentation coverage

#### Work with Contracts
1. Run `./scripts/dev.sh forge-build` - Build contracts
2. Run `./scripts/dev.sh bindings` - Generate Go bindings
3. See [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md) - Contract workflow

#### Use Scripts
1. Read [SCRIPTS_REFERENCE.md](SCRIPTS_REFERENCE.md) - Script documentation
2. Run `./scripts/dev.sh help` - See available commands

#### Before Commit
```bash
./scripts/dev.sh test all
./scripts/dev.sh check-compliance
```

#### Before Push
```bash
./scripts/dev.sh test all
./scripts/dev.sh test race
./scripts/dev.sh audit
./scripts/dev.sh check-compliance
./scripts/dev.sh check-docs
```

---

## Document Status

| Document | Status | Last Updated |
|----------|--------|--------------|
| SPEC.md | ✅ Complete | 2025-11-11 |
| CLAUDE.md | ✅ Complete | 2025-11-11 |
| DEVELOPMENT_SETUP.md | ✅ Complete | 2025-11-11 |
| AUDIT_AND_TESTING.md | ✅ Complete | 2025-11-11 |
| SCRIPTS_REFERENCE.md | ✅ Complete | 2025-11-11 |
| planning/00_V2_MASTER_PLAN.md | ✅ Complete | 2025-11-03 |
| planning/07_TASK_BREAKDOWN.md | ✅ Complete | 2025-11-03 |

---

## Documentation Philosophy

### Principles

1. **Single Source of Truth**: SPEC.md is authoritative for technical requirements
2. **Practical Guidance**: CLAUDE.md provides day-to-day workflow
3. **Comprehensive Coverage**: All aspects documented with examples
4. **Consistent Format**: All docs follow same structure
5. **Living Documents**: Updated with code changes

### Organization

```
docs/
├── README.md                    # This file (index)
├── DEVELOPMENT_SETUP.md         # Setup guide
├── AUDIT_AND_TESTING.md         # Testing guide
├── SCRIPTS_REFERENCE.md         # Scripts reference
└── planning/                    # Architecture planning
    ├── 00_V2_MASTER_PLAN.md
    ├── 01_MODULARITY_REQUIREMENTS.md
    └── 07_TASK_BREAKDOWN.md

Root:
├── SPEC.md                      # Technical specification
├── CLAUDE.md                    # Development guidelines
└── README.md                    # Project overview
```

---

## Contributing to Documentation

### Adding New Documentation

1. Place in appropriate location (`docs/` or root)
2. Update this index (docs/README.md)
3. Link from relevant documents
4. Follow existing formatting style
5. Include code examples
6. Add to "Document Status" table

### Documentation Standards

- **Format**: Markdown with GitHub flavors
- **Code blocks**: Include language hint (```bash, ```go)
- **Links**: Use relative paths
- **Examples**: Real, working examples only
- **Structure**: Clear headings, table of contents
- **Length**: Comprehensive but concise
- **Voice**: Second person ("You should...")

### When to Update

- SPEC.md changes → Update all docs referencing requirements
- New script added → Update SCRIPTS_REFERENCE.md
- New workflow → Update DEVELOPMENT_SETUP.md
- New testing approach → Update AUDIT_AND_TESTING.md
- Process change → Update CLAUDE.md

---

## Getting Help

If documentation is unclear or missing:

1. Check all relevant docs using this index
2. Search for keywords across all docs
3. Check SPEC.md for authoritative requirements
4. Review script source code in `scripts/`
5. Open issue describing documentation gap

---

## External Resources

- [Foundry Book](https://book.getfoundry.sh/) - Foundry documentation
- [Go Testing](https://pkg.go.dev/testing) - Go testing package
- [Arbitrum Sequencer Feed](https://www.degencode.com/p/decoding-the-arbitrum-sequencer-feed) - Sequencer protocol
- [Abigen](https://geth.ethereum.org/docs/tools/abigen) - Go binding generator