docs: review and correct comments and documentation (#436)

hosts/idols-ai/VR.md

@@ -6,10 +6,10 @@ to run, but compatibility still depends on the game and translation layer.
 
 ## First activation and persistence
 
-Run `just niri` on idols-ai from this branch's worktree, or after merging it. Log out and back in so
-Steam sees `PRESSURE_VESSEL_IMPORT_OPENXR_1_RUNTIMES=1`. That variable is what makes pressure-vessel
-mount WiVRn's `$XDG_RUNTIME_DIR/wivrn/comp_ipc` socket into a game's container; without it the
-game's OpenXR client fails with `ERROR_RUNTIME_UNAVAILABLE` and the headset stays black.
+Run `just niri` on idols-ai. Log out and back in so Steam sees
+`PRESSURE_VESSEL_IMPORT_OPENXR_1_RUNTIMES=1`. That variable is what makes pressure-vessel mount
+WiVRn's `$XDG_RUNTIME_DIR/wivrn/comp_ipc` socket into a game's container; without it the game's
+OpenXR client fails with `ERROR_RUNTIME_UNAVAILABLE` and the headset stays black.
 
 The root filesystem is a 4 GiB tmpfs. These directories are preserved with mode 0700:
 

hosts/idols-ai/default.nix

@@ -41,7 +41,8 @@ in
   ];
 
   # Zram consumes physical memory for compression, which can cause a deadlock and system hang if the model size approaches the physical memory limit.
-  # Disable the whole module (zram device + its swappiness=180 sysctl tunings); this host uses a disk swapfile instead.
+  # Disable the whole module (zram device + its swappiness=180 sysctl tunings); this host uses a
+  # disk swapfile instead, created by disko at /swap (see ./disko-fs.nix). The two must move together.
   modules.zram.enable = false;
 
   # zswap: compressed writeback cache in front of the disk swapfile.
@@ -93,8 +94,9 @@ in
   networking = {
     inherit hostName;
 
-    # we use networkd instead
-    networkmanager.enable = false; # provides nmcli/nmtui for wifi adjustment
+    # off: this host uses networkd (below). NetworkManager would otherwise
+    # provide nmcli/nmtui for wifi adjustment.
+    networkmanager.enable = false;
     useDHCP = false;
   };
 
@@ -117,7 +119,7 @@ in
       ];
       DNS = nameservers;
       DHCP = "ipv6"; # enable DHCPv6 only, so we can get a GUA.
-      IPv6AcceptRA = true; # for Stateless IPv6 Autoconfiguraton (SLAAC)
+      IPv6AcceptRA = true; # for Stateless IPv6 Autoconfiguration (SLAAC)
       LinkLocalAddressing = "ipv6";
       # r8169 drops carrier on S3 resume; without this, networkd tears down the
       # static address/route and mihomo's TUN auto-detect briefly loses its

hosts/idols-ai/preservation.nix

@@ -469,13 +469,11 @@ in
     "D! /var/lib/systemd/coredump 0755 root root"
   ];
 
-  # systemd-machine-id-commit.service would fail but it is not relevant
-  # in this specific setup for a persistent machine-id so we disable it
-  #
-  # see the firstboot example below for an alternative approach
+  # Mask the commit service: /etc/machine-id is persisted by preservation
+  # (see the `files` entry above), so there is no transient ID to commit.
   systemd.suppressedSystemUnits = [ "systemd-machine-id-commit.service" ];
 
-  # let the service commit the transient ID to the persistent volume
+  # Inert while the unit is masked above; kept as the alternative approach.
   systemd.services.systemd-machine-id-commit = {
     unitConfig.ConditionPathIsMountPoint = [
       ""

hosts/idols-ai/restic.nix

@@ -3,9 +3,6 @@
   ...
 }:
 {
-  # Part 1 of the backup plan: a local restic repository on this machine.
-  # The off-machine target (youko, or a cloud) is a later step.
-  #
   # Be specific here and keep `exclude` minimal: an allowlist of the
   # irreplaceable directories beats backing up a broad tree and excluding half
   # of it. Large files anywhere are skipped by size (excludeLargerThan), which