diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..d10bd51
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,115 @@
+# Laptop Migration: MacBook → x86_64 NixOS
+
+## Order of operations
+
+### 1. Install NixOS
+Boot the NixOS ISO on the new laptop. Partition, format, mount to `/mnt`.
+```bash
+# Generate base config
+nixos-generate-config --root /mnt
+
+# Then rebuild from the flake (replaces generated config):
+sudo nixos-rebuild switch --flake git+https://os.scoble.me/forgejo/sscoble/laptop-config.git#laptop --root /mnt
+```
+
+### 2. First build: npmDepsHash
+The first `nixos-rebuild` will fail with a hash mismatch error for pi-coding-agent. The error output contains the correct hash:
+```
+error: hash mismatch in fixed-output derivation ...
+  specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+  got:       sha256-1q2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1q=
+```
+
+Copy the `got:` hash, paste into `flake.nix` → `npmDepsHash = "sha256-..."`. Commit, push, rebuild.
+
+### 3. Transfer secrets (before reboot!)
+From the MacBook, while both laptops are on the same LAN:
+```bash
+# SSH keys
+scp ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.pub new-laptop:~/.ssh/
+
+# Pi agent config (has API keys — do NOT commit to git)
+scp ~/.pi/agent/SYSTEM.md new-laptop:~/.pi/agent/
+scp ~/.pi/agent/models.json new-laptop:~/.pi/agent/
+scp ~/.pi/agent/mcp.json new-laptop:~/.pi/agent/
+scp ~/.pi/agent/settings.json new-laptop:~/.pi/agent/
+scp ~/.pi/agent/auth.json new-laptop:~/.pi/agent/
+
+# Wallpapers
+scp ~/path/to/wallpaper.jpg new-laptop:~/wallpapers/default.jpg
+```
+
+### 4. Transfer projects
+Push any repos not yet in Forgejo, then re-clone:
+```bash
+# From MacBook: push scobleclaw to Forgejo
+cd ~/Projects/scobleclaw
+git remote add forgejo https://os.scoble.me/forgejo/sscoble/scobleclaw.git
+git push forgejo main
+
+# From new laptop: re-clone
+cd ~/Projects
+git clone https://os.scoble.me/forgejo/sscoble/scobleclaw.git
+git clone https://os.scoble.me/forgejo/sscoble/wgu.git
+
+# Other projects: rsync or push individually
+rsync -avz --progress ~/Projects/other-project/ new-laptop:~/Projects/other-project/
+```
+
+### 5. Transfer documents and media
+```bash
+# Documents (small, ~30MB)
+rsync -avz --progress ~/Documents/ new-laptop:~/Documents/
+
+# Personal media (larger — be selective)
+rsync -avz --progress ~/Pictures/ new-laptop:~/Pictures/
+rsync -avz --progress ~/Music/ new-laptop:~/Music/
+```
+
+### 6. Reboot and login
+```bash
+sudo reboot
+# Login via greetd → sscoble password → Hyprland starts
+# SUPER+Return → ghostty with zellij
+```
+
+### 7. Verify everything works
+```bash
+pi                              # pi agent should start
+qmd status                      # vault search
+zotero                          # reference manager
+obsidian ~/vault                # vault notes
+code ~/Projects/scobleclaw      # VS Code
+
+# OB1 tunnel
+ssh -fNL 3987:localhost:3987 n97-mini
+curl -s http://localhost:3987/health  # should return ok
+
+# Discord: @mention Marcus in #speaker-site
+```
+
+## Files to NOT transfer
+These contain caches, build artifacts, or macOS-specific junk:
+- `~/Library/` — macOS only
+- `~/Applications/` — macOS apps
+- `~/.ollama/` — model cache (too large, re-download)
+- `~/.cargo/` — rust cache
+- `~/.bun/` — bun cache
+- `~/.npm/` — npm cache
+- `~/go/` — go module cache
+- `~/tmp/` — temp files
+- `~/Downloads/` — temp downloads (clean first, then selectively transfer)
+- `~/.Trash/` — obviously
+
+## Post-migration checklist
+- [ ] `pi` works
+- [ ] `qmd status` works
+- [ ] `vscode` opens with typst LSP
+- [ ] `zotero` launches
+- [ ] `obsidian ~/vault` opens vault
+- [ ] `brave` launches and syncs
+- [ ] SSH keys work (`ssh n97-mini`)
+- [ ] OB1 tunnel works
+- [ ] Hyprland: SUPER+D opens rofi, SUPER+Return opens ghostty+zellij
+- [ ] Discord: @mention Marcus → gets a reply
+- [ ] Wallpaper appears after login