Add btrfs implementation plan

- Create PLAN-archangel-btrfs.org with 6-phase implementation
- Phases: Refactor, Btrfs, Multi-disk, Testing, CLI tools, Docs
- Add TODO referencing the plan

1 files changed, 209 insertions, 0 deletions

diff --git a/docs/PLAN-archangel-btrfs.org b/docs/PLAN-archangel-btrfs.org
new file mode 100644
index 0000000..ea39bf6
--- /dev/null
+++ b/docs/PLAN-archangel-btrfs.org
@@ -0,0 +1,209 @@
+#+TITLE: Implementation Plan: Archangel Btrfs Support
+#+DATE: 2026-01-23
+
+* Overview
+
+Add btrfs filesystem support to archangel (formerly archzfs) installer.
+Users can choose ZFS or Btrfs during installation.
+
+See [[file:research-btrfs-expansion.org][research-btrfs-expansion.org]] for background research.
+
+* Key Decisions (Already Made)
+
+- Project rename: archzfs → archangel
+- Snapshot tool: snapper + snap-pac + grub-btrfs
+- Bootloader: ZFS uses ZFSBootMenu, Btrfs uses GRUB
+- Encryption: ZFS native, Btrfs uses LUKS
+- RAID: Btrfs raid1 only (raid5/6 unstable)
+- Layout: Btrfs subvols mirror ZFS datasets
+
+* Phase 1: Refactor Current Installer
+
+Goal: Modularize install-archzfs before adding btrfs.
+
+** 1.1 Create lib/ directory structure
+- [ ] Create custom/lib/ directory
+- [ ] Move color/output functions → lib/common.sh
+- [ ] Move fzf prompt functions → lib/common.sh
+- [ ] Move config file handling → lib/config.sh
+
+** 1.2 Extract ZFS-specific code
+- [ ] Create lib/zfs.sh
+- [ ] Move pool creation → lib/zfs.sh
+- [ ] Move dataset creation → lib/zfs.sh
+- [ ] Move ZFS mount logic → lib/zfs.sh
+- [ ] Move ZFSBootMenu install → lib/zfs.sh
+
+** 1.3 Extract shared disk operations
+- [ ] Create lib/disk.sh
+- [ ] Move partitioning logic (EFI + root)
+- [ ] Move disk selection/validation
+- [ ] Move RAID detection logic
+
+** 1.4 Add filesystem selection prompt
+- [ ] Add fzf prompt: "Filesystem: ZFS / Btrfs"
+- [ ] Store choice in config
+- [ ] Gate ZFS vs Btrfs code paths
+
+** 1.5 Rename project
+- [ ] Rename install-archzfs → archangel
+- [ ] Update build.sh references
+- [ ] Update README.org
+- [ ] Update all internal references
+
+* Phase 2: Implement Btrfs Support
+
+Goal: Full btrfs installation path.
+
+** 2.1 Create lib/btrfs.sh
+- [ ] Create btrfs volume function
+- [ ] Create subvolume creation function
+- [ ] Create mount function (with correct options)
+- [ ] Create fstab generation (NO subvolid!)
+
+** 2.2 Subvolume layout
+Create these subvolumes (matching ZFS datasets):
+- [ ] @ → /
+- [ ] @home → /home
+- [ ] @snapshots → /.snapshots (snapper requirement)
+- [ ] @var_log → /var/log
+- [ ] @var_cache → /var/cache
+- [ ] @tmp → /tmp
+- [ ] @var_tmp → /var/tmp
+- [ ] @media → /media (compress=off)
+- [ ] @vms → /vms (nodatacow)
+- [ ] @var_lib_docker → /var/lib/docker
+
+** 2.3 Mount options
+#+BEGIN_SRC
+BTRFS_OPTS="noatime,compress=zstd,space_cache=v2,discard=async"
+#+END_SRC
+- [ ] Apply to all subvols except @media (compress=off) and @vms (nodatacow)
+
+** 2.4 Snapper configuration
+- [ ] Install snapper, snap-pac packages
+- [ ] Create /etc/snapper/configs/root
+- [ ] Set timeline policy (hourly=6, daily=7, weekly=2, monthly=1)
+- [ ] Enable snapper-timeline.timer
+- [ ] Enable snapper-cleanup.timer
+
+** 2.5 GRUB + grub-btrfs installation
+- [ ] Install grub, grub-btrfs packages
+- [ ] Configure GRUB for btrfs root
+- [ ] Enable grub-btrfsd service (auto-update on snapshots)
+- [ ] Test snapshot appears in GRUB menu
+
+** 2.6 Genesis snapshot
+- [ ] Create initial snapshot: snapper create -d "genesis"
+- [ ] Verify appears in snapper list
+- [ ] Verify appears in GRUB menu
+
+** 2.7 LUKS encryption (optional)
+- [ ] Add encryption prompt (yes/no)
+- [ ] Create LUKS container on root partition
+- [ ] Configure crypttab
+- [ ] Add encrypt hook to mkinitcpio
+- [ ] Test passphrase prompt at boot
+
+* Phase 3: Multi-disk Btrfs
+
+Goal: Mirror support for btrfs.
+
+** 3.1 Btrfs RAID1 creation
+- [ ] Detect multi-disk selection
+- [ ] Create raid1 volume: mkfs.btrfs -d raid1 -m raid1 /dev/sdX /dev/sdY
+- [ ] Handle 2+ disk configurations
+
+** 3.2 EFI redundancy
+- [ ] Create EFI partition on all disks
+- [ ] Install GRUB to all EFI partitions
+- [ ] Create boot entries for each disk
+
+** 3.3 Degraded boot support
+- [ ] Add degraded mount option for emergency
+- [ ] Document recovery procedure
+
+* Phase 4: Testing Infrastructure
+
+Goal: Automated tests for all configurations.
+
+** 4.1 Test configs
+- [ ] Create test-configs/zfs-single.conf
+- [ ] Create test-configs/zfs-mirror.conf
+- [ ] Create test-configs/btrfs-single.conf
+- [ ] Create test-configs/btrfs-mirror.conf
+- [ ] Create test-configs/btrfs-encrypted.conf
+
+** 4.2 Test scripts
+- [ ] Create test-btrfs-single.sh
+- [ ] Create test-btrfs-mirror.sh
+- [ ] Update test-vm.sh for btrfs option
+
+** 4.3 Validation checks (per research doc)
+- [ ] Fresh install checks
+- [ ] Reboot survival checks
+- [ ] Snapshot operation checks
+- [ ] Rollback + reboot checks
+- [ ] Failure recovery checks (multi-disk)
+- [ ] Encryption checks
+
+* Phase 5: CLI Tools
+
+Goal: Unified snapshot management wrappers.
+
+** 5.1 archangel-snapshot
+- [ ] Detect filesystem (ZFS vs Btrfs)
+- [ ] ZFS: call zfs snapshot
+- [ ] Btrfs: call snapper create
+- [ ] Consistent interface for both
+
+** 5.2 archangel-rollback
+- [ ] Detect filesystem
+- [ ] ZFS: call zfsrollback script
+- [ ] Btrfs: call snapper rollback
+- [ ] Include reboot prompt (required for full rollback)
+
+** 5.3 archangel-list
+- [ ] List snapshots for either filesystem
+- [ ] Consistent output format
+
+* Phase 6: Documentation
+
+Goal: Update all docs for dual-filesystem support.
+
+** 6.1 README.org
+- [ ] Update project name to archangel
+- [ ] Document filesystem choice
+- [ ] Update feature list
+- [ ] Update usage examples
+
+** 6.2 RESCUE-GUIDE.txt
+- [ ] Add btrfs recovery procedures
+- [ ] Add snapper commands
+- [ ] Add GRUB recovery for btrfs
+
+** 6.3 New docs
+- [ ] Create BTRFS.org with btrfs-specific details
+- [ ] Update NOTES.org project context
+
+* Schedule (Suggested Order)
+
+1. Phase 1 (Refactor) - do first, enables everything else
+2. Phase 2 (Btrfs single-disk) - core functionality
+3. Phase 4.1-4.2 (Test infra) - validate as we go
+4. Phase 3 (Multi-disk) - after single-disk works
+5. Phase 5 (CLI tools) - polish
+6. Phase 6 (Docs) - ongoing, finalize at end
+
+* Dependencies
+
+- Phase 2 depends on Phase 1 (refactored code)
+- Phase 3 depends on Phase 2 (btrfs basics)
+- Phase 4 can run in parallel with 2-3
+- Phase 5 depends on Phase 2
+- Phase 6 is ongoing
+
+* Open Items
+
+- [ ] File ZFSBootMenu rollback bug
+- [ ] Decide: offer archsetup --chroot during install? (TODO exists)