add Phase 2A container and recovery readiness gates

docs/le-app-database-migration/phase2a-host-maintenance/grub-btrfs-readiness.md

@@ -0,0 +1,78 @@
+# GRUB and grub-btrfs readiness
+
+Verified baseline:
+
+- GRUB has normal, fallback, and recovery entries for both `linux-zen` and
+  standard `linux`.
+- Snapper snapshots 1, 2, and 3 exist.
+- `/boot/grub/grub-btrfs.cfg` is absent, so there are currently no generated
+  snapshot entries.
+- `grub-btrfs-snapper.path` is active and watching `/.snapshots`.
+
+The installed unit definitions are:
+
+```ini
+# /usr/lib/systemd/system/grub-btrfs-snapper.path
+[Unit]
+Description=Monitors for new snapshots
+
+[Path]
+PathModified=/.snapshots
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```ini
+# /usr/lib/systemd/system/grub-btrfs-snapper.service
+[Unit]
+Description=Regenerate grub-btrfs.cfg
+
+[Service]
+Type=oneshot
+Environment="PATH=/sbin:/bin:/usr/sbin:/usr/bin"
+EnvironmentFile=/etc/default/grub-btrfs/config
+ExecStart=bash -c 'if [[ -z $(/usr/bin/findmnt -n / | /usr/bin/grep "\.snapshots") ]]; then if [ -s "${GRUB_BTRFS_GRUB_DIRNAME:-/boot/grub}/grub-btrfs.cfg" ]; then /etc/grub.d/41_snapshots-btrfs; else ${GRUB_BTRFS_MKCONFIG:-grub-mkconfig} -o ${GRUB_BTRFS_GRUB_DIRNAME:-/boot/grub}/grub.cfg; fi; fi'
+```
+
+The bounded July 12 journal contains only these two parser warnings and no
+recorded service activation that generated snapshot entries:
+
+```text
+Jul 12 17:16:42 TITANSERVER systemd[1]: /usr/lib/systemd/system/grub-btrfs-snapper.service:11: Ignoring unknown escape sequences in the ExecStart expression containing "\.snapshots".
+Jul 12 17:18:23 TITANSERVER systemd[1]: /usr/lib/systemd/system/grub-btrfs-snapper.service:11: Ignoring unknown escape sequences in the ExecStart expression containing "\.snapshots".
+```
+
+The most supportable
+inference is that the watcher was enabled after snapshots 1–3 or received no
+qualifying modification afterward; absence of `grub-btrfs.cfg` confirms that the
+generator has not completed successfully for those snapshots.
+
+The separately approved standalone generation and verification procedure is:
+
+```bash
+/etc/grub.d/41_snapshots-btrfs
+generate_rc=$?
+printf 'grub_btrfs_generate_rc=%s\n' "$generate_rc"
+
+test -s /boot/grub/grub-btrfs.cfg
+present_rc=$?
+printf 'grub_btrfs_cfg_present_rc=%s\n' "$present_rc"
+
+grub-script-check /boot/grub/grub-btrfs.cfg
+syntax_rc=$?
+printf 'grub_btrfs_cfg_syntax_rc=%s\n' "$syntax_rc"
+
+grep -E 'snapshot|Snapshot|snapper|\.snapshots' /boot/grub/grub-btrfs.cfg
+entries_rc=$?
+printf 'grub_btrfs_entries_rc=%s\n' "$entries_rc"
+
+grep -q 'snapshots-btrfs' /boot/grub/grub.cfg
+main_menu_link_rc=$?
+printf 'grub_main_menu_snapshot_link_rc=%s\n' "$main_menu_link_rc"
+```
+
+This procedure is not approved or executed by the maintenance scripts. If the
+last check fails, stop: making the submenu reachable would require a separately
+approved `grub-mkconfig -o /boot/grub/grub.cfg`. Do not regenerate full GRUB as
+an incidental readiness repair.