Adding all files and folders

docs/03_file_migration_guide.md

@@ -0,0 +1,105 @@
+# 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`.