docs: add the post-install checklist and podman/camera-udev notes

The checklist is the standing home for manual post-first-boot steps: bluetooth pairing and the Proton Bridge login start it. The podman-socket and camera-udev notes carry the evidence for the filed install-time task, including why uaccess alone can't grant a raw USB node.

2 files changed, 118 insertions, 0 deletions

diff --git a/docs/design/2026-08-07-podman-socket-and-camera-udev.md b/docs/design/2026-08-07-podman-socket-and-camera-udev.md
new file mode 100644
index 0000000..7eb99e8
--- /dev/null
+++ b/docs/design/2026-08-07-podman-socket-and-camera-udev.md
@@ -0,0 +1,70 @@
+# Enable podman.socket at install time (and one related USB rule)
+
+From winvm, 2026-08-07 on ratio.
+
+## 1. The ask: enable the rootless podman socket
+
+    systemctl --user enable --now podman.socket
+
+**What was wrong.** On ratio this was `disabled` / `inactive`, and
+`$XDG_RUNTIME_DIR/podman/podman.sock` did not exist at all. Podman's CLI does
+not need it, so nothing surfaces the gap until something speaks the REST API.
+
+**Why it matters.** Every podman GUI and API client connects over that socket
+rather than by shelling out. I installed Pods (`com.github.marhkb.Pods`,
+flathub) to manage the Windows VM container, and without the socket it opens to
+an empty window with no useful error — it looks like the app is broken or has no
+containers, when in fact there is nothing listening. That is a bad first-run
+experience and a hard one to diagnose from the symptom.
+
+It is socket-activated, so enabling it costs nothing while idle: podman starts
+on demand when a client connects, and `enable` brings the socket back on login
+without a daemon sitting resident. This is the ordinary way to run the podman
+API rootless.
+
+**Verified after enabling:** socket present at
+`/run/user/1000/podman/podman.sock`, the API answers
+`/v5.0.0/libpod/containers/json`, and it reported the `WinVM` container.
+
+**One Flatpak note worth recording**, because it looks like a problem and is
+not. The Pods flatpak ships `xdg-run/podman:ro` in its filesystem permissions,
+which reads as though a client could not connect. Tested from inside the
+sandbox: the socket is visible, and both readable *and writable*, so the
+read-only directory mount does not block the connection. No `flatpak override`
+is needed.
+
+**Client-side, not your problem but context:** Pods stores connections in
+`~/.var/app/com.github.marhkb.Pods/config/pods/` and only writes that file after
+the user adds a connection through the UI, so it can't be pre-seeded from an
+install script without inventing the format. The one-time step is adding
+`unix:///run/user/1000/podman/podman.sock` as a connection; a
+`last-used-connection` gsetting makes it stick after that. So the *socket* is
+the part worth automating, and the connection is not.
+
+## 2. Related, same category — a udev rule for USB camera passthrough
+
+Filing this alongside because it is the same class of one-time machine-level
+setup and it will bite on velox the same way. Take it or leave it separately
+from item 1.
+
+`/etc/udev/rules.d/99-usb-passthrough-cameras.rules`:
+
+    SUBSYSTEM=="usb", ATTR{idVendor}=="3564", ATTR{idProduct}=="ff02", GROUP="video", MODE="0660", TAG+="uaccess"
+    SUBSYSTEM=="usb", ATTR{idVendor}=="046d", ATTR{idProduct}=="085e", GROUP="video", MODE="0660", TAG+="uaccess"
+
+(3564:ff02 is the OBSBOT, 046d:085e the Logitech BRIO.)
+
+**Why.** Streaming a USB camera into the VM runs `usbredirect`, which must open
+the device read-write to claim it and detach the kernel drivers. The node
+defaults to `crw-rw-r-- root:root`, so a normal user has read but no write and
+the attach fails with a bare "Failed to open device!".
+
+**The part worth writing down:** `TAG+="uaccess"` alone is NOT enough, though it
+looks like the right answer and `udevadm test` confirms the tag is applied.
+logind does not turn that tag into an ACL on a raw `/dev/bus/usb/*` node — it
+manages ACLs for a narrower set of seat devices. The `GROUP`/`MODE` grant is
+what actually works. The tag is kept because it is harmless and correct in
+principle; it just isn't sufficient. I lost time on that, so it is recorded
+rather than left to be rediscovered.
+
+Both items are live on ratio and neither exists on velox.
diff --git a/docs/post-install-checklist.org b/docs/post-install-checklist.org
new file mode 100644
index 0000000..fa704b6
--- /dev/null
+++ b/docs/post-install-checklist.org
@@ -0,0 +1,48 @@
+#+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
+
+** 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=).
+
+** Proton Mail Bridge (cmail)
+
+The installer's completion message carries the steps; recorded here too so
+the checklist is complete:
+
+1. Clone claude-templates to =~/projects/claude-templates= if missing.
+2. Run =protonmail-bridge --cli=, log in, then quit.
+3. Run =~/code/archsetup/scripts/cmail-setup-finish.sh=.
+4. First mail sync: =mbsync cmail && mu index=.