docs: Clarify preserve-var migration guarantees

Explain that atomic per-entry namespace visibility does not make the migration a tree-wide snapshot or transaction, and distinguish both from crash durability. This helps operators reason about partial migrations and live database data.

Assisted-by: AI

Author: ckyrouac

docs/src/bootc-installation.7.md

@@ -296,10 +296,14 @@ previous installation.
 
 With the OSTree backend, `--preserve-var` copies the old `/var` into the new
 deployment before rebooting. It uses reflinks when supported and otherwise makes a
-full copy; neither strategy is a consistent snapshot of live data. Stop stateful
-services before copying their data. A completed copy is not guaranteed to survive
-sudden power loss or a kernel failure. `/var/tmp`, `/var/cache`, `/var/log/journal`,
-and `/var/lib/containers` are always excluded. Use repeatable
+full copy. Each new entry is staged and renamed into place atomically for
+namespace visibility. This is not a tree-wide point-in-time snapshot or a
+global all-or-nothing transaction: the copy proceeds over time, and a later
+failure can leave a partial migration. Neither strategy provides a consistent
+snapshot of live data; stop stateful services before copying their data. There
+is no crash-durability guarantee: copied content and renames are not guaranteed
+to survive sudden power loss or a kernel failure. `/var/tmp`, `/var/cache`,
+`/var/log/journal`, and `/var/lib/containers` are always excluded. Use repeatable
 `--preserve-var-skip PATH` options or the `preserve-var-skip` install configuration
 key for additional relative paths below `/var`.
 

docs/src/man/bootc-install-to-existing-root.8.md

@@ -19,10 +19,14 @@ to be cleaned up if desired when rebooted into the new root.
 The opt-in `--preserve-var` option copies the running system's `/var` into the
 new deployment before rebooting. It requires the OSTree backend, uses reflinks
 when supported, and otherwise performs a full copy. Reflinks are created per
-file, not as an atomic snapshot; stop stateful services or use a consistent
-snapshot before copying live database data. A completed copy is not guaranteed
-to survive sudden power loss or a kernel failure. The paths `tmp`, `cache`,
-`log/journal`, and `lib/containers` are always excluded. Repeat
+file. Each new entry is staged and renamed into place atomically for namespace
+visibility, but the migration is not a tree-wide point-in-time snapshot or a
+global all-or-nothing transaction: it proceeds over time, and a later failure
+can leave a partial migration. The copy is not a consistent snapshot of live
+data; stop stateful services or use a consistent snapshot before copying live
+database data. There is no crash-durability guarantee: copied content and
+renames are not guaranteed to survive sudden power loss or a kernel failure.
+The paths `tmp`, `cache`, `log/journal`, and `lib/containers` are always excluded. Repeat
 `--preserve-var-skip` to exclude additional paths relative to `/var`; each path
 may contain at most one slash, for example `lib/rpm`.