# Documentation Index

> **Last Updated**: 2025-12-21 (OPNsense WAN config, DHCP isolation strategy)
> **IMPORTANT**: Update this index whenever you modify documentation files

## Quick Reference

Need to know... | Check this file
--- | ---
Node IPs, service locations, storage paths | `INFRASTRUCTURE.md`
Service configs, API keys, copy/paste configs | `CONFIGURATIONS.md`
Why we made a decision, common patterns | `DECISIONS.md`
What's currently being worked on | `TASKS.md`
Recent changes and when they happened | `CHANGELOG.md`

## Core Documentation Files

### INFRASTRUCTURE.md
**Purpose**: Single source of truth for all infrastructure
**Contains**:
- Cluster node IPs and specs
- Complete service map with IPs, ports, domains
- Storage architecture (NFS mounts, local storage, ZFS)
- Network configuration
- Important file paths

**Update when**: Infrastructure changes (new service, IP change, storage mount)

---

### CONFIGURATIONS.md
**Purpose**: Detailed service configurations
**Contains**:
- Traefik SSL/TLS setup
- Service routing examples
- API keys and credentials
- Copy/paste ready config snippets
- Service-specific settings

**Update when**: Service configuration changes, API keys rotate, new services added

---

### DECISIONS.md
**Purpose**: Architecture decisions and patterns
**Contains**:
- Why we chose LXC vs Docker for services
- Authentication strategy
- File permission standards (777 for media)
- Common troubleshooting patterns
- Known issues and workarounds

**Update when**: Making architectural decisions, discovering new patterns, solving recurring issues

---

### TASKS.md
**Purpose**: Track ongoing work and TODO items
**Contains**:
- Active tasks being worked on
- Pending tasks
- Blocked items
- Task priority

**Update when**: Starting new work, completing tasks, discovering new work

---

### CHANGELOG.md
**Purpose**: Historical record of changes
**Contains**:
- Date-stamped entries for all significant changes
- Who made the change (user/Claude)
- What was changed and why
- Links to relevant commits or files

**Update when**: After completing any significant work

---

## Legacy Files (To Be Removed)

These files will be consolidated into the core docs above:

- ~~`infrastructure-map.md`~~ → Merged into `INFRASTRUCTURE.md`
- ~~`home-assistant-traefik.md`~~ → Merged into `CONFIGURATIONS.md`
- ~~`traefik-ssl-setup.md`~~ → Merged into `CONFIGURATIONS.md`
- ~~`recyclarr-setup.md`~~ → Merged into `CONFIGURATIONS.md`

Keep for reference (detailed info):
- `cluster-state.md` - Detailed cluster topology
- `inventory.md` - Complete VM/LXC inventory
- `network.md` - Detailed network info
- `storage.md` - Detailed storage info
- `services.md` - Service dependencies and details

## Documentation Workflow

### When Making Changes

1. **Before starting**: Check `INFRASTRUCTURE.md` for current state
2. **During work**: Note what you're changing
3. **After completing**:
   - Update relevant core doc (`INFRASTRUCTURE.md`, `CONFIGURATIONS.md`, or `DECISIONS.md`)
   - Add entry to `CHANGELOG.md` with date and description
   - Update `TASKS.md` to mark work complete
   - Update `README.md` (this file) Last Updated date

### Example Workflow

```
Task: Add new service "Tautulli" to monitor Jellyfin

1. Check INFRASTRUCTURE.md → Find next available IP
2. Deploy service
3. Update INFRASTRUCTURE.md → Add Tautulli to service map
4. Update CONFIGURATIONS.md → Add Tautulli config snippet
5. Update CHANGELOG.md → "2025-11-17: Added Tautulli LXC..."
6. Update TASKS.md → Mark "Deploy Tautulli" as complete
7. Update README.md → Change Last Updated date
```

## File Organization

```
docs/
├── README.md              ← You are here (index and guide)
├── INFRASTRUCTURE.md      ← Infrastructure reference
├── CONFIGURATIONS.md      ← Service configurations
├── DECISIONS.md           ← Architecture decisions
├── TASKS.md               ← Current/ongoing tasks
├── CHANGELOG.md           ← Historical changes
├── cluster-state.md       ← [Keep] Detailed topology
├── inventory.md           ← [Keep] Full VM/LXC list
├── network.md             ← [Keep] Network details
├── storage.md             ← [Keep] Storage details
└── services.md            ← [Keep] Service details
```

## Maintenance

- Review and update docs weekly
- Clean up completed tasks monthly
- Archive old changelog entries yearly
- Verify INFRASTRUCTURE.md matches reality regularly