@@ -92,13 +92,14 @@ sudo atomic-rebuild-uki 20250208-134725                # rebuild UKI for specifi
 
 ### Shell completion
 
-Tab completion is available for `atomic-gc` and `atomic-rebuild-uki` in both zsh and bash:
+Tab completion is available for `atomic-gc`, `atomic-rebuild-uki`, and `atomic-upgrade` in both zsh and bash:
 
 ```bash
 atomic-gc <TAB>              # → list  rm
 atomic-gc rm <TAB>           # → generation IDs from ESP
 atomic-rebuild-uki <TAB>     # → generation IDs from ESP
 atomic-rebuild-uki -<TAB>    # → --help --list -h -l
+atomic-upgrade -<TAB>        # → --dry-run --tag --no-gc --separate-home ...
 ```
 
 Completions are installed automatically. For bash, the `bash-completion` package must
@@ -159,6 +160,7 @@ Edit `/etc/atomic.conf`:
 | `KERNEL_PARAMS` | *(security defaults)* | Kernel command line parameters |
 | `SBCTL_SIGN` | `0` | Sign UKI files with sbctl for Secure Boot (`0`=off, `1`=on) |
 | `UPGRADE_GUARD` | `1` | Upgrade guard: block direct `pacman -Syu` (`0`=off, `1`=on) |
+| `HOME_COPY_FILES` | *(empty)* | Files to copy into isolated home subvolumes (see [Experimental home isolation](#experimental-home-isolation)) |
 
 Default `KERNEL_PARAMS`: `rw slab_nomerge init_on_alloc=1 page_alloc.shuffle=1 pti=on vsyscall=none randomize_kstack_offset=on debugfs=off`
 
@@ -240,6 +242,59 @@ sudo atomic-upgrade -- bash -c '/usr/bin/pacman -Syu && sudo -u YOUR_USER yay -S
 > upgrade applies to the live system and is **not atomic**. The next
 > `atomic-upgrade` will snapshot whatever state the live system is in.
 
+## Experimental home isolation
+
+> **This feature is for throwaway experiments, not permanent environments.**
+> Permanent setups should use regular generations with the shared `/home` subvolume.
+
+`--separate-home` creates an isolated `/home` subvolume for the generation — so
+experiments with dotfiles, DE configs, or user-level packages don't pollute your
+main home. If something goes wrong, delete the generation and the home subvolume
+is orphaned; GC will warn you about it.
+
+```bash
+# Try KDE without touching your current home
+sudo atomic-upgrade --separate-home -t kde -- pacman -S plasma-meta
+
+# Experiment with dev tooling, bring specific dotfiles
+sudo atomic-upgrade --separate-home -t dev --copy-files ".bashrc .ssh .gitconfig" -- pacman -S base-devel
+
+# Dry run to preview
+sudo atomic-upgrade --dry-run --separate-home -t test
+```
+
+**How it works:**
+
+1. A new Btrfs subvolume `home-TAG` is created (or reused if it already exists)
+2. User directories are created with correct ownership (users with UID ≥ 1000)
+3. Files listed in `--copy-files` (or `HOME_COPY_FILES` from config) are copied from
+   current `/home/<user>/` into the new home
+4. The generation's fstab is updated so `/home` points to the new subvolume
+
+**Constraints:**
+
+- Requires `--tag` (the home subvolume is named `home-TAG`)
+- `--copy-files` requires `--separate-home`
+- File paths with spaces are not supported
+- Absolute paths and `..` traversal are rejected for safety
+
+**Cleanup:** GC never auto-deletes home subvolumes (they contain user data). When
+all generations referencing a tag are gone, GC reports the orphan:
+
+```
+   Orphan home: home-kde (no generations with tag 'kde')
+   To remove: btrfs subvolume delete /run/atomic/temp_root/home-kde
+```
+
+A default set of files to copy can be configured:
+
+```bash
+# /etc/atomic.conf
+HOME_COPY_FILES=".bashrc .bash_profile .ssh .gnupg .gitconfig"
+```
+
+The `--copy-files` flag overrides `HOME_COPY_FILES` per invocation.
+
 ## Disk space checks
 
 Before creating a snapshot, `atomic-upgrade` checks available disk space on both the Btrfs filesystem and the ESP:
@@ -255,6 +310,8 @@ If disk space cannot be determined (e.g. `btrfs` and `df` both fail), a warning
 - `root-*` subvolumes that have no matching UKI on the ESP
 - UKI files on the ESP that have no matching subvolume
 
+Orphan `home-*` subvolumes (where no generation with that tag exists) are **reported but never auto-deleted** — they may contain user data. Use `btrfs subvolume delete` to remove them manually.
+
 If the ESP is not mounted during the orphan sweep phase, it is skipped with a warning — orphans will be cleaned up on the next run.
 
 ## Components
@@ -265,11 +322,11 @@ If the ESP is not mounted during the orphan sweep phase, it is skipped with a wa
 | `atomic-gc` | Generation management — garbage collection, list, manual delete |
 | `atomic-guard` | Pacman hook — blocks direct `-Syu`, allows installs/removes |
 | `atomic-rebuild-uki` | Rebuild UKI for existing snapshot |
-| `common.sh` | Shared library (config, locking, btrfs, UKI build, GC) |
+| `common.sh` | Shared library (config, locking, btrfs, UKI build, GC, home skeleton) |
 | `fstab.py` | Safe fstab editing (atomic write + verification + rollback) |
 | `rootdev.py` | Auto-detect root device type (LUKS/LVM/plain) and build kernel cmdline |
 | `pacman-wrapper` | Optional `/usr/local/bin/pacman` wrapper |
-| `completions/` | Zsh and bash tab completions for `atomic-gc` and `atomic-rebuild-uki` |
+| `completions/` | Zsh and bash tab completions for `atomic-gc`, `atomic-rebuild-uki`, and `atomic-upgrade` |
 
 ## Troubleshooting
 
 
@@ -27,6 +27,11 @@ Subvolumes that have no matching UKI on the ESP.
 .IP \[bu] 2
 UKI files that have no matching subvolume.
 .PP
+Orphan \f[I]home\-*\f[R] subvolumes (created by
+\f[B]\-\-separate\-home\f[R]) are \f[B]reported but never
+auto\-deleted\f[R] \[em] they may contain user data.
+A message with the manual deletion command is printed for each orphan.
+.PP
 If the ESP is not mounted during the orphan sweep, it is skipped with a
 warning.
 .SH SUBCOMMANDS
 
@@ -31,6 +31,10 @@ sweep removes:
 - Subvolumes that have no matching UKI on the ESP.
 - UKI files that have no matching subvolume.
 
+Orphan *home-\** subvolumes (created by **\--separate-home**) are **reported
+but never auto-deleted** — they may contain user data. A message with the
+manual deletion command is printed for each orphan.
+
 If the ESP is not mounted during the orphan sweep, it is skipped with a
 warning.
 
 
@@ -1,15 +1,13 @@
 .\" Automatically generated by Pandoc 3.5
 .\"
-.TH "" "" "" ""
-.SS \[ga]\[ga]\[ga]markdown
-title: ATOMIC\-UPGRADE section: 8 header: System Administration footer:
-atomic\-upgrade \[em]
+.TH "ATOMIC\-UPGRADE" "8" "" "atomic\-upgrade" "System Administration"
 .SH NAME
 atomic\-upgrade \[em] atomic system upgrades for Arch Linux on Btrfs
 .SH SYNOPSIS
 \f[B]atomic\-upgrade\f[R] [\f[B]\-n\f[R]|\f[B]\-\-dry\-run\f[R]]
 [\f[B]\-t\f[R]|\f[B]\-\-tag\f[R] \f[I]TAG\f[R]] [\f[B]\-\-no\-gc\f[R]]
-[\f[B]\-\-\f[R] \f[I]COMMAND\f[R]\&...]
+[\f[B]\-\-separate\-home\f[R]] [\f[B]\-\-copy\-files\f[R] \f[I]\[lq]FILE
+\&...\[rq]\f[R]] [\f[B]\-\-\f[R] \f[I]COMMAND\f[R]\&...]
 .PP
 \f[B]atomic\-rebuild\-uki\f[R] [\f[B]\-l\f[R]|\f[B]\-\-list\f[R]]
 \f[I]GEN_ID\f[R]
@@ -52,6 +50,21 @@ Example: \f[B]\-t pre\-nvidia\f[R] creates
 \f[B]\-\-no\-gc\f[R]
 Skip garbage collection after a successful upgrade.
 .TP
+\f[B]\-\-separate\-home\f[R]
+Create an isolated \f[I]/home\f[R] Btrfs subvolume for this generation.
+The subvolume is named \f[I]home\-TAG\f[R], so \f[B]\-\-tag\f[R] is
+required.
+If a subvolume with that name already exists, it is reused.
+See \f[B]EXPERIMENTAL HOME ISOLATION\f[R] below.
+.TP
+\f[B]\-\-copy\-files\f[R] \f[I]\[lq]FILE \&...\[rq]\f[R]
+Space\-separated list of files to copy from the current
+\f[I]/home//\f[R] into the new home subvolume.
+Paths are relative to the user\[cq]s home directory.
+Requires \f[B]\-\-separate\-home\f[R].
+Overrides \f[B]HOME_COPY_FILES\f[R] from \f[B]atomic.conf\f[R](5).
+Paths with spaces are not supported.
+.TP
 \f[B]\-\-\f[R] \f[I]COMMAND\f[R]\&...
 Run \f[I]COMMAND\f[R] in the snapshot chroot instead of the default
 \f[B]pacman \-Syu\f[R].
@@ -61,6 +74,26 @@ Show usage summary and exit.
 .TP
 \f[B]\-V\f[R], \f[B]\-\-version\f[R]
 Show version and exit.
+.SH EXPERIMENTAL HOME ISOLATION
+\f[B]This feature is for throwaway experiments, not permanent
+environments.\f[R] Permanent setups should use regular generations with
+the shared \f[I]/home\f[R] subvolume.
+.PP
+When \f[B]\-\-separate\-home\f[R] is used, the generation gets its own
+\f[I]/home\f[R] subvolume so that experiments with dotfiles, desktop
+environment configs, or user\-level packages do not affect the main
+home.
+If the experiment fails, delete the generation; garbage collection will
+report the orphan home subvolume but will \f[B]never auto\-delete
+it\f[R] (it may contain user data).
+.PP
+The home subvolume is populated with empty user directories (matching
+users with UID >= 1000) and, optionally, specific files copied from the
+current home via \f[B]\-\-copy\-files\f[R] or the
+\f[B]HOME_COPY_FILES\f[R] config option.
+.PP
+Safety: absolute paths and \f[B]..\f[R] traversal in file lists are
+rejected.
 .SH UPGRADE GUARD
 Two guard layers prevent accidental direct system upgrades, controlled
 by the \f[B]UPGRADE_GUARD\f[R] option in \f[B]atomic.conf\f[R](5)
@@ -176,6 +209,18 @@ Upgrade with a custom tag:
 sudo atomic\-upgrade \-t pre\-nvidia
 .EE
 .PP
+Experiment with KDE in isolated home (throwaway):
+.IP
+.EX
+sudo atomic\-upgrade \-\-separate\-home \-t kde \-\- pacman \-S plasma\-meta
+.EE
+.PP
+Experiment with dev tools, copying dotfiles:
+.IP
+.EX
+sudo atomic\-upgrade \-\-separate\-home \-t dev \-\-copy\-files \[dq].bashrc .ssh\[dq] \-\- pacman \-S base\-devel
+.EE
+.PP
 Rebuild a missing UKI:
 .IP
 .EX
 
@@ -1,4 +1,3 @@
-```markdown
 ---
 title: ATOMIC-UPGRADE
 section: 8
@@ -12,7 +11,7 @@ atomic-upgrade — atomic system upgrades for Arch Linux on Btrfs
 
 # SYNOPSIS
 
-**atomic-upgrade** [**-n**|**\--dry-run**] [**-t**|**\--tag** *TAG*] [**\--no-gc**] [**\--** *COMMAND*...]
+**atomic-upgrade** [**-n**|**\--dry-run**] [**-t**|**\--tag** *TAG*] [**\--no-gc**] [**\--separate-home**] [**\--copy-files** *"FILE ..."*] [**\--** *COMMAND*...]
 
 **atomic-rebuild-uki** [**-l**|**\--list**] *GEN_ID*
 
@@ -50,6 +49,18 @@ Use it to recover an accidentally deleted *.efi* file.
 **\--no-gc**
 :   Skip garbage collection after a successful upgrade.
 
+**\--separate-home**
+:   Create an isolated */home* Btrfs subvolume for this generation. The
+    subvolume is named *home-TAG*, so **\--tag** is required. If a subvolume
+    with that name already exists, it is reused. See **EXPERIMENTAL HOME
+    ISOLATION** below.
+
+**\--copy-files** *"FILE ..."*
+:   Space-separated list of files to copy from the current */home/<user>/*
+    into the new home subvolume. Paths are relative to the user's home
+    directory. Requires **\--separate-home**. Overrides **HOME_COPY_FILES**
+    from **atomic.conf**(5). Paths with spaces are not supported.
+
 **\--** *COMMAND*...
 :   Run *COMMAND* in the snapshot chroot instead of the default
     **pacman -Syu**.
@@ -60,6 +71,24 @@ Use it to recover an accidentally deleted *.efi* file.
 **-V**, **\--version**
 :   Show version and exit.
 
+# EXPERIMENTAL HOME ISOLATION
+
+**This feature is for throwaway experiments, not permanent environments.**
+Permanent setups should use regular generations with the shared */home*
+subvolume.
+
+When **\--separate-home** is used, the generation gets its own */home*
+subvolume so that experiments with dotfiles, desktop environment configs,
+or user-level packages do not affect the main home. If the experiment fails,
+delete the generation; garbage collection will report the orphan home
+subvolume but will **never auto-delete it** (it may contain user data).
+
+The home subvolume is populated with empty user directories (matching users
+with UID >= 1000) and, optionally, specific files copied from the current
+home via **\--copy-files** or the **HOME_COPY_FILES** config option.
+
+Safety: absolute paths and **..** traversal in file lists are rejected.
+
 # UPGRADE GUARD
 
 Two guard layers prevent accidental direct system upgrades, controlled by the
@@ -161,6 +190,14 @@ Upgrade with a custom tag:
 
     sudo atomic-upgrade -t pre-nvidia
 
+Experiment with KDE in isolated home (throwaway):
+
+    sudo atomic-upgrade --separate-home -t kde -- pacman -S plasma-meta
+
+Experiment with dev tools, copying dotfiles:
+
+    sudo atomic-upgrade --separate-home -t dev --copy-files ".bashrc .ssh" -- pacman -S base-devel
+
 Rebuild a missing UKI:
 
     sudo atomic-rebuild-uki 20250208-134725
 
@@ -74,6 +74,15 @@ Enable the upgrade guard (pacman hook and wrapper).
 Set to \f[B]1\f[R] to block direct \f[B]pacman \-Syu\f[R], \f[B]0\f[R]
 to allow it.
 Default: \f[B]1\f[R].
+.TP
+\f[B]HOME_COPY_FILES\f[R]
+Space\-separated list of files to copy from \f[I]/home//\f[R] into
+isolated home subvolumes created with \f[B]\-\-separate\-home\f[R].
+Paths are relative to the user\[cq]s home directory.
+The \f[B]\-\-copy\-files\f[R] flag on the command line overrides this
+value per invocation.
+Paths with spaces are not supported.
+Default: \f[I](empty)\f[R].
 .SH SECURITY
 The configuration file must be owned by root.
 If the file is owned by another user, it is rejected and no values are
@@ -122,6 +131,12 @@ Keep more generations:
 .EX
 KEEP_GENERATIONS=5
 .EE
+.PP
+Default files for isolated homes:
+.IP
+.EX
+HOME_COPY_FILES=\[dq].bashrc .bash_profile .ssh .gnupg .gitconfig\[dq]
+.EE
 .SH SEE ALSO
 \f[B]atomic\-upgrade\f[R](8), \f[B]atomic\-gc\f[R](8),
 \f[B]sbctl\f[R](8), \f[B]pacman.conf\f[R](5)
@@ -70,6 +70,13 @@ rejected entirely.
 :   Enable the upgrade guard (pacman hook and wrapper). Set to **1** to
     block direct **pacman -Syu**, **0** to allow it. Default: **1**.
 
+**HOME_COPY_FILES**
+:   Space-separated list of files to copy from */home/<user>/* into isolated
+    home subvolumes created with **\--separate-home**. Paths are relative to
+    the user's home directory. The **\--copy-files** flag on the command line
+    overrides this value per invocation. Paths with spaces are not supported.
+    Default: *(empty)*.
+
 # SECURITY
 
 The configuration file must be owned by root. If the file is owned by
@@ -108,6 +115,10 @@ Keep more generations:
 
     KEEP_GENERATIONS=5
 
+Default files for isolated homes:
+
+    HOME_COPY_FILES=".bashrc .bash_profile .ssh .gnupg .gitconfig"
+
 # SEE ALSO
 
 **atomic-upgrade**(8), **atomic-gc**(8), **sbctl**(8), **pacman.conf**(5)