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)

./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)

./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:

# 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