# Phase 3: File Migration Scripting Guide

**Objective:** To prepare for the physical relocation of user data from the old directory structures to the new, consolidated structure on the NixOS system.

**Prerequisite:** A full analysis of the disk and file reconnaissance log (`logs/01_system_recon.log`) must be complete. The target directory structure should be agreed upon.

**Core Principle:** We will not move files directly. We will write a script that **copies** the files. The original data will be left untouched until the new NixOS system is fully configured and the copied data is verified. We will also implement a `--dry-run` feature for safety.

---

### Target Directory for Staging

To avoid disturbing the existing file structure on the 2.7TB drive, the migration script should consolidate all files from the Windows and old Ubuntu partitions into a single, new directory.

-   **Staging Directory:** `/mnt/ubuntu_storage_3TB/migration_staging`

The script's primary purpose is to copy data from the other drives *into* this location. From there, you can organize it manually at your leisure after the migration is complete.

---


### Instructions for Operator (Human or AI)

Your task is to create a shell script named `scripts/02_migrate_files.sh`. This script will contain a series of `rsync` commands to copy data from the source drives to the target directories.

#### 1. Script Requirements

- **Shebang:** The script must start with `#!/bin/bash`.
- **Safety:** The script should not perform any operations if run as root without a specific override.
- **Dry-Run Flag:** The script must accept a `--dry-run` argument. If this flag is present, all `rsync` commands should be executed with the `--dry-run` flag, which shows what would be done without making any actual changes.
- **Verbosity:** All commands should be verbose (`-v`) and output human-readable sizes (`-h`) so the user can see the progress.
- **Logging:** The script should log its output to a file in the `logs/` directory.

#### 2. Source Data Locations

The script will need to access data from the following locations. These drives will be mounted on the running NixOS system *before* the script is executed (as defined in `configuration.nix`).

- **Primary Ubuntu Home:** `/home/sam/` on the old root partition. (This will need to be mounted temporarily during migration).
- **Ubuntu Storage Drive:** The contents of `/dev/sdd1` (which will become `/data`). The script will mostly be organizing files *within* this drive.
- **Windows Storage Drive:** `/mnt/windows-storage` (mounted from `/dev/sdb2`).
- **Windows User Folders:** The script may need to access `C:\Users\<YourUsername>` from one of the `ntfs` partitions.

#### 3. `rsync` Command Structure

Use the `rsync` command for all file copy operations. It is efficient, safe, and preserves metadata.

**Example `rsync` command for the script:**
```bash
# -a: archive mode (preserves permissions, ownership, etc.)
# -v: verbose
# -h: human-readable numbers
# --progress: show progress during transfer
# --exclude='*.tmp': example of excluding files

rsync -avh --progress --exclude='cache' /path/to/source/documents/ /data/work/
```

#### 4. Script Skeleton (to be created in `scripts/02_migrate_files.sh`)

```bash
#!/bin/bash

# ---
# Configuration ---
# ---
LOG_FILE="logs/02_file_migration.log"
DRY_RUN=""

# Check for --dry-run flag
if [ "$1" == "--dry-run" ]; then
    DRY_RUN="--dry-run"
    echo "---
PERFORMING DRY RUN ---"
fi

# ---
# Helper Functions ---
# ---
log() {
    echo "$1" | tee -a "$LOG_FILE"
}

# ---
# Main Execution ---
# ---
log "Starting file migration script..."

# Create target directories
log "Creating target directories..."
mkdir -p $DRY_RUN /data/personal /data/work /data/dev /data/backups /data/media

# ---
# Migration Commands ---
# ---
# Add rsync commands here. Be specific.

# Example:
# log "Migrating Documents from Windows..."
# rsync -avh $DRY_RUN /mnt/windows-storage/Users/Sam/Documents/ /data/work/project-archives/


log "File migration script finished."
```

**Next Step:** A developer or another AI instance will now write the full `scripts/02_migrate_files.sh` script based on these instructions and a deeper analysis of the file contents revealed in `logs/02_deeper_scan.log`.