proxmox/reports/ROOT_FILES_ORGANIZATION_GUIDE.md

# Root Directory Files Organization Guide

**Date**: 2026-01-06  
**Script**: `scripts/organize-root-files.sh`

---

## 📋 Overview

This script organizes files in the project root directory by moving them to appropriate subdirectories based on file type and purpose.

---

## 🎯 Purpose

The root directory should contain only essential configuration files. This script moves:
- Log files → `logs/`
- CSV inventory files → `reports/inventory/`
- Shell scripts → `scripts/`
- Python scripts → `scripts/`
- JavaScript scripts → `scripts/`
- HTML examples → `examples/`
- JSON/Text reports → `reports/`

---

## 🚀 Usage

### Dry Run (Preview Changes)
```bash
./scripts/organize-root-files.sh
# or
./scripts/organize-root-files.sh --dry-run
```

This will show what files would be moved without actually moving them.

### Execute (Actually Move Files)
```bash
./scripts/organize-root-files.sh --execute
```

This will actually move the files to their new locations.

---

## 📁 File Organization Rules

### Log Files → `logs/`
- All `*.log` files
- Examples: `MARKDOWN_CLEANUP_EXECUTION.log`, `dependency_update_log_*.log`

### CSV Inventory Files → `reports/inventory/`
- All `container_inventory_*.csv` files
- Container inventory snapshots

### Shell Scripts → `scripts/`
- All `*.sh` files from root
- Examples: `INSTALL_TUNNEL.sh`, `fix-all-tunnels.sh`

### Python Scripts → `scripts/`
- All `*.py` files from root
- Examples: `list_vms.py`, `list_vms_with_tunnels.py`

### JavaScript Scripts → `scripts/`
- All `*.js` files from root (except `package.json`, `pnpm-lock.yaml`, `token-list.json`)
- Examples: `query-omada-devices.js`, `test-omada-connection.js`

### HTML Examples → `examples/`
- All `*.html` files
- Examples: `add-rpc-network.html`, `wallet-connect.html`

### JSON/Text Reports → `reports/`
- `CONTENT_INCONSISTENCIES.json`
- `MARKDOWN_ANALYSIS.json`
- `REFERENCE_FIXES_REPORT.json`
- `CONVERSION_SUMMARY.txt`

---

## ✅ Files That Stay in Root

These files should **NOT** be moved (they're essential configuration):

- `README.md` - Main project documentation
- `PROJECT_STRUCTURE.md` - Project structure documentation
- `package.json` - pnpm workspace configuration
- `pnpm-workspace.yaml` - Workspace definition
- `pnpm-lock.yaml` - Dependency lock file
- `.gitignore` - Git ignore rules
- `.gitmodules` - Git submodules configuration
- `claude_desktop_config.json.example` - Configuration template
- `token-list.json` - Token list data file

---

## 📊 Expected Results

### Before Organization
- Root directory: ~52 files
- Log files: 7+ files in root
- Scripts: 20+ files in root
- Reports: 4+ files in root

### After Organization
- Root directory: ~8 essential files
- Log files: All in `logs/`
- Scripts: All in `scripts/`
- Reports: All in `reports/`
- Examples: All in `examples/`

---

## 🔍 Safety Features

1. **Dry Run Mode**: Default mode shows what would happen without making changes
2. **Skip Existing**: Won't overwrite files that already exist in destination
3. **Error Handling**: Tracks errors and continues processing
4. **Logging**: Creates detailed log file of all operations
5. **Directory Creation**: Automatically creates destination directories

---

## 📝 Log File

The script creates a log file: `ROOT_FILES_ORGANIZATION_YYYYMMDD_HHMMSS.log`

This log contains:
- All file moves
- Warnings (skipped files)
- Errors (failed moves)
- Summary statistics

---

## ⚠️ Important Notes

1. **Backup First**: Consider backing up important files before running
2. **Review Dry Run**: Always review dry-run output before executing
3. **Git Status**: Check git status after running to see changes
4. **Update References**: Update any scripts/docs that reference moved files

---

## 🔄 After Running

After organizing files, you may need to:

1. **Update Script References**: If other scripts reference moved files, update paths
2. **Update Documentation**: Update docs that reference moved files
3. **Git Commit**: Commit the organization changes
4. **Verify**: Test that moved scripts still work from new locations

---

## 📊 Example Output

```
╔══════════════════════════════════════════════════════════╗
║   Root Directory Files Organization                     ║
╚══════════════════════════════════════════════════════════╝

=== Moving Log Files to logs/ ===
Would move: 138.log → logs/138.log (log file)
Would move: MARKDOWN_CLEANUP_EXECUTION.log → logs/MARKDOWN_CLEANUP_EXECUTION.log (log file)
...

=== Moving Shell Scripts to scripts/ ===
Would move: INSTALL_TUNNEL.sh → scripts/INSTALL_TUNNEL.sh (shell script)
...

Summary:
  Files Moved: 0
  Files Skipped: 0
  Errors: 0

⚠️  DRY RUN MODE - No files were actually moved

To execute the moves, run:
  ./scripts/organize-root-files.sh --execute
```

---

## ✅ Verification

After running, verify the organization:

```bash
# Check root directory
find . -maxdepth 1 -type f ! -name ".*" | wc -l

# Check logs directory
ls logs/ | wc -l

# Check scripts directory
ls scripts/*.sh scripts/*.py scripts/*.js 2>/dev/null | wc -l

# Check reports directory
ls reports/*.json reports/*.txt 2>/dev/null | wc -l
```

---

*Guide created: 2026-01-06*