1 files changed, 108 insertions, 0 deletions
diff --git a/docs/post-install-checklist.org b/docs/post-install-checklist.org
new file mode 100644
index 0000000..8c48938
--- /dev/null
+++ b/docs/post-install-checklist.org
@@ -0,0 +1,108 @@
+#+TITLE: Post-Install Checklist
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-08-08
+
+* About
+
+Manual steps a fresh archsetup install cannot automate — things that are
+inherently interactive (pairing, account logins) or that need judgment on the
+specific machine. Work through this after first boot. When a new manual step
+is discovered during a machine setup, add it here rather than leaving it in a
+session note; the installer's outro already points at the Proton Bridge steps,
+and this file is the home for the rest.
+
+Steps that CAN be automated don't belong here — file them as installer tasks
+instead. The 2026-04-10 velox setup notes were triaged exactly that way:
+microcode, radio state, and the ZFS /tmp mask went into the installer;
+bluetooth pairing landed below.
+
+* Checklist
+
+** Run the post-rebuild check first
+
+Before working through the manual steps below, run:
+
+#+begin_src sh
+~/code/archsetup/scripts/post-rebuild-check
+#+end_src
+
+It runs the five checks a rebuilt machine actually needs — failed units,
+user units that are present but never enabled, =*.example= configs whose
+real sibling is missing, gitignore-mode projects missing the working state
+their own =.gitignore= names, and the signal-cli registration. Each prints
+a line whether or not it finds anything; exit 1 means something needs
+attention.
+
+These are the gaps velox hit within two days of its 2026-08-13 reinstall,
+and three of the five looked fine on casual inspection: a stowed unit file,
+an enabled-looking timer, a present git clone. Run it again a day or two
+after the install, once timers have had a chance to fail.
+
+It normally finishes in a second or two. On a machine whose user systemd is
+wedged it takes a couple of minutes instead, because every =systemctl= call
+is bounded at five seconds and check 2 makes one per unit. That is the slow
+case working as intended: it reports what it could not read rather than
+hanging. Set =PRC_SYSTEMCTL_TIMEOUT= lower to cut the wait.
+
+** Pair bluetooth peripherals
+
+Pairing is inherently interactive (scan, pick the device, confirm), so it
+can't ride the installer. For a mouse (e.g. the Logi M650):
+
+#+begin_src sh
+bluetoothctl
+# inside the prompt:
+#   scan on          — wait for the device to appear
+#   pair <MAC>
+#   trust <MAC>      — trust makes it auto-reconnect at boot
+#   connect <MAC>
+#   scan off
+#+end_src
+
+Trusted devices reconnect on their own after reboot; if one doesn't, check
+=rfkill list= first (radios should be unblocked — TLP owns radio state and
+enables bluetooth/wifi at startup per =/etc/tlp.d/01-custom.conf=).
+
+** Brightness control on a machine installed before 2026-08-13
+
+Only for a machine whose install predates =configure_backlight_access=. New
+installs get the rule automatically, and a re-run of =archsetup= skips the
+step because =essential_services= is already marked complete, so an older
+machine needs one of these by hand:
+
+#+begin_src bash
+# either drop the rule in directly...
+sudo tee /etc/udev/rules.d/90-backlight.rules > /dev/null << 'EOF'
+ACTION=="add", SUBSYSTEM=="backlight", RUN+="/usr/bin/chgrp video /sys/class/backlight/%k/brightness"
+ACTION=="add", SUBSYSTEM=="backlight", RUN+="/usr/bin/chmod g+w /sys/class/backlight/%k/brightness"
+ACTION=="add", SUBSYSTEM=="leds", KERNEL=="*kbd_backlight", RUN+="/usr/bin/chgrp video /sys/class/leds/%k/brightness"
+ACTION=="add", SUBSYSTEM=="leds", KERNEL=="*kbd_backlight", RUN+="/usr/bin/chmod g+w /sys/class/leds/%k/brightness"
+EOF
+sudo udevadm control --reload
+sudo udevadm trigger --subsystem-match=backlight --action=add
+sudo udevadm trigger --subsystem-match=leds --action=add
+
+# ...or clear the marker and re-run just that step
+sudo rm /var/lib/archsetup/state/essential_services
+#+end_src
+
+Verify: =ls -l /sys/class/backlight/*/brightness= shows group =video= with
+=g+w=, and =brightnessctl -c backlight set 70%= succeeds without sudo.
+
+Only laptops have these devices; on a desktop the rule is inert and nothing
+needs doing.
+
+** Proton Mail Bridge (cmail)
+
+The installer's completion message carries the steps; recorded here too so
+the checklist is complete:
+
+1. Run =protonmail-bridge --cli=, log in, then quit.
+2. Run =~/code/archsetup/scripts/cmail-setup-finish.sh=.
+3. First mail sync: =mbsync cmail && mu index=.
+
+Sending mail also needs =cmail-action= on PATH, which rulesets owns: clone it
+to =~/code/rulesets= and run =make install=. That is not a prerequisite for the
+steps above — the setup script warns and carries on — but =mbsync= is the first
+thing that wants it. An agent session runs =make install= at startup, so on a
+machine that runs them the link appears on its own.