Prune stale dotfiles commentary

3 files changed, 58 insertions, 184 deletions

diff --git a/nix/common.nix b/nix/common.nix
index 7290395..c256aa2 100644
--- a/nix/common.nix
+++ b/nix/common.nix
@@ -1,31 +1,12 @@
-{ config, pkgs, lib, dotfilesRoot, ... }:
+{
+  config,
+  pkgs,
+  lib,
+  dotfilesRoot,
+  ...
+}:
 
-# Shared Home-Manager module: ONLY package installation. Dotfile deployment is
-# owned by chezmoi on both the Arch host and the remote-dev VM. Keeping this
-# module deployment-agnostic prevents home-manager from conflicting with
-# chezmoi-owned files (which would otherwise materialize as `.backup` files on
-# every `nix-switch`).
-#
-# Policy: this profile carries leaf CLI tools, editor/AI-agent runtimes
-# (node, uv), and build *orchestrators* (cmake, ninja, ccache, sccache).
-# It must NEVER carry actual compilers or linkers — those would shadow
-# the system's and silently link projects against nixpkgs glibc/libstdc++
-# instead of the system sysroot.
-#
-# Forbidden on PATH from this module: cc, c++, gcc, g++, clang, clang++,
-# ld, ld.lld, ar, nm, objcopy, make, meson, pkg-config, autoconf,
-# automake, libtool, python, python3, pip, cargo, rustc, go.
-#
-# Allowed: orchestrators that delegate to whatever compiler is in PATH
-# (cmake, ninja, ccache, sccache), instrumentation/analysis that hooks
-# at the syscall/library boundary (valgrind, gdb, lldb, strace), and
-# source-only tooling (doxygen, clang-tools — clangd/clang-format/
-# clang-tidy, no compiler driver). Project-specific compilers/linkers
-# go in project-local flake.nix + direnv `.envrc`, NOT here.
-#
-# Editor/AI runtimes: node, npm, npx (via `nodejs`), uv, uvx (via `uv`
-# — manages its own python interpreters under XDG, doesn't install a
-# system python3).
+# Shared Home-Manager package profile. Chezmoi owns dotfile deployment.
 
 {
   home.stateVersion = "25.05";
@@ -53,8 +34,6 @@
     glow
 
     # Git stack
-    # Includes git-send-email: nixpkgs wraps it with the SMTP/SASL Perl deps
-    # it needs, so we don't carry distro Perl modules just for email support.
     (git.override { sendEmailSupport = true; })
     gh
     delta
@@ -94,19 +73,15 @@
     openssh
     mosh
 
-    # Debug / trace / profile — moved off pacman. User policy: only
-    # used against own builds, so glibc/kernel version skew vs the
-    # system isn't an issue. Only `perf` stays system (it links against
-    # the running kernel ABI; pacman's matches the kernel package).
+    # Debug / trace / profile
     gdb
-    lldb        # also brings lldb-dap (used by dap.lua via type="lldb")
+    lldb # also brings lldb-dap (used by dap.lua via type="lldb")
     strace
     samply
     t-rec
     valgrind
 
-    # Build orchestrators — these only delegate to whatever compiler is
-    # in PATH; they don't ship cc/c++/ld themselves, so no shadowing.
+    # Build orchestrators
     cmake
     ninja
     ccache
@@ -123,19 +98,12 @@
     pandoc
 
     # Secrets — `pass-otp` is wired as an extension so `pass otp ...`
-    # works against the same store. `pass` from pacman is removed.
+    # works against the same store.
     gnupg
     pinentry-curses
     (pass.withExtensions (exts: [ exts.pass-otp ]))
 
-    # C/C++ source tooling (no compiler driver in PATH).
-    # clang-tools ships clangd/clang-format/clang-tidy and most of the
-    # python helpers (git-clang-format, clang-format-diff, clang-tidy-diff)
-    # but skips run-clang-tidy because the symlink loop in nixpkgs'
-    # clang-tools derivation gates on the +x bit and run-clang-tidy
-    # loses it during the multi-output split. Re-expose it ourselves
-    # from clang-unwrapped's `python` output (tries both the modern
-    # bin/ layout and the legacy share/clang/ layout).
+    # C/C++ source tooling
     clang-tools
     (runCommand "run-clang-tidy" { } ''
       mkdir -p $out/bin
@@ -151,49 +119,33 @@
       exit 1
     '')
 
-    # CI runner (drives podman; act itself is just a Go binary)
+    # CI runner
     act
 
     # ── Rootless podman ─────────────────────────────────────────────────────
-    # Moved off pacman so the host and VM run the same nix-pinned stack.
-    # The nix `podman` is wrapped to find these helpers via /nix/store
-    # paths, so we don't need a containers.conf for `helper_binaries_dir`.
-    # Per-user containers config (registries/storage/policy) lives under
-    # chezmoi at `dot_config/containers/`.
     podman
-    crun         # OCI runtime (lighter than runc; default for rootless)
-    conmon       # container monitor process
-    netavark     # default network stack on podman 4+
+    crun # OCI runtime (lighter than runc; default for rootless)
+    conmon # container monitor process
+    netavark # default network stack on podman 4+
     aardvark-dns # DNS for netavark networks
-    slirp4netns  # rootless user-mode networking
-    passt        # pasta backend (slirp4netns successor; podman picks it up)
+    slirp4netns # rootless user-mode networking
+    passt # pasta backend (slirp4netns successor; podman picks it up)
     podman-compose
-    # `docker` shell shim → podman. nixpkgs has no top-level
-    # `podman-docker` attr (Arch ships one as a convenience pkg); the
-    # NixOS option `virtualisation.podman.dockerCompat` exists but isn't
-    # reachable from home-manager, so we ship a one-line writer instead.
+    # `docker` shell shim → podman.
     (writeShellScriptBin "docker" ''exec ${podman}/bin/podman "$@"'')
 
-    # Editor/AI agent runtimes — NOT for project builds (see policy above)
+    # Editor/AI agent runtimes
     nodejs_24 # copilot-language-server requires Node 24 (see ai.lua)
-    uv        # for project tooling that asks for `uv`/`uvx`; brings no python
+    uv # for project tooling that asks for `uv`/`uvx`; brings no python
     python3Packages.ipython # interactive REPL; pulls its own python, only `ipython` lands on PATH
 
     # AI coding agents
     claude-code
-    codex # OpenAI Codex CLI (rust rewrite); replaces pacman openai-codex-bin
+    codex # OpenAI Codex CLI
     github-copilot-cli # `copilot`; prebuilt-binary derivation since 1.0.43
     tuicr # interactive git-change reviewer; flake input, see nix/flake.nix. Skill: dot_claude/skills/tuicr/
 
     # ── LSPs / formatters / linters / DAPs ─────────────────────────────────
-    # Replaces Mason entirely (phase p6 of the nix migration rips out
-    # mason-tool-installer). The set tracks the previous
-    # `ensure_installed` list in dot_config/nvim/lua/plugins/lsp.lua, with
-    # five niche tools dropped: groovy-language-server (Mason-only build,
-    # upstream stale), npm-groovy-lint, nginx-language-server,
-    # nginx-config-formatter, systemdlint (all rarely-edited domains;
-    # losing them is acceptable).
-
     # LSPs
     actionlint
     autotools-language-server
@@ -208,7 +160,7 @@
     systemd-language-server
     taplo
     typescript-language-server
-    vscode-langservers-extracted   # cssls + html + jsonls + eslint
+    vscode-langservers-extracted # cssls + html + jsonls + eslint
     yaml-language-server
 
     # Formatters
@@ -228,13 +180,7 @@
     typos
     yamllint
 
-    # DAPs / debuggers — `lldb-dap` ships in pkgs.lldb (declared in the
-    # debug/trace block above). dap configs in plugins/debug.lua target
-    # it via `type = "lldb"`.
-
-    # Zsh and plugins (loaded from $HOME/.nix-profile/share/... by the
-    # shared zshrc; nix-profile path is preferred, system path is the
-    # fallback for un-bootstrapped states).
+    # Zsh and plugins
     zsh
     zsh-completions
     zsh-syntax-highlighting
diff --git a/nix/host.nix b/nix/host.nix
index 5a3d8a9..c44319e 100644
--- a/nix/host.nix
+++ b/nix/host.nix
@@ -1,28 +1,14 @@
-{ config, pkgs, lib, dotfilesRoot, ... }:
+{
+  config,
+  pkgs,
+  lib,
+  dotfilesRoot,
+  ...
+}:
 
-# Arch host Home-Manager profile. Layered on top of `common.nix`; adds
-# only host-specific concerns that don't make sense on the VM (wayland
-# session tools, Yubikey, host-only CLIs / GUIs).
-#
-# Dotfile deployment on the host is owned entirely by **chezmoi** (run
-# via `just apply` / `just sync`). Home-Manager here only installs
-# binaries and writes the host-only smartcard config below.
-#
-# Migration policy: a tool lives here iff nixpkgs ships a working
-# equivalent AND it has no tight system coupling (no setuid, no
-# /usr/lib/systemd/system unit, no udev rule, no system D-Bus
-# activation, no /usr/share/wayland-sessions entry, no shared lib that
-# other pacman pkgs link, no system fontconfig path, no PAM, no Qt
-# plugin search path, no kernel/firmware/initramfs touchpoint).
-# User-scope systemd units are NOT system coupling — nix drops them in
-# ~/.nix-profile/share/systemd/user/ and systemd picks them up.
+# Arch host Home-Manager package profile.
 
 let
-  # Whisper.cpp base model — packaged inline because nixpkgs doesn't
-  # ship the .bin blobs. Sourced from the upstream huggingface mirror
-  # (same URL the AUR `whisper.cpp-model-base` uses). The dictate script
-  # at dot_local/bin/executable_dictate defaults to
-  # ~/.nix-profile/share/whisper-cpp-models/ggml-base.bin.
   whisper-cpp-model-base = pkgs.stdenvNoCC.mkDerivation rec {
     pname = "whisper-cpp-model-base";
     version = "1.0";
@@ -70,10 +56,12 @@ let
       mainProgram = "pass-secret-service";
     };
   };
-  arkenfox-userjs-profile = pkgs.runCommand "arkenfox-userjs-profile-${pkgs.arkenfox-userjs.version}" { } ''
-    install -Dm644 ${pkgs.arkenfox-userjs}/user.js $out/share/arkenfox-userjs/user.js
-    install -Dm644 ${pkgs.arkenfox-userjs}/user.cfg $out/share/arkenfox-userjs/user.cfg
-  '';
+  arkenfox-userjs-profile =
+    pkgs.runCommand "arkenfox-userjs-profile-${pkgs.arkenfox-userjs.version}" { }
+      ''
+        install -Dm644 ${pkgs.arkenfox-userjs}/user.js $out/share/arkenfox-userjs/user.js
+        install -Dm644 ${pkgs.arkenfox-userjs}/user.cfg $out/share/arkenfox-userjs/user.cfg
+      '';
 in
 {
   imports = [ ./common.nix ];
@@ -81,58 +69,29 @@ in
   home.username = builtins.getEnv "USER";
   home.homeDirectory = builtins.getEnv "HOME";
 
-  # Keep Nix's compiler out of PATH, but make it available to host Neovim for
-  # nvim-treesitter parser builds. The Nix-provided Neovim loads these parser
-  # .so files, so using the Nix compiler wrapper is the coherent ABI choice.
+  # Used by nvim-treesitter parser builds without adding a compiler to PATH.
   home.sessionVariables.NVIM_TREESITTER_CC = "${pkgs.stdenv.cc}/bin/cc";
 
   home.packages = with pkgs; [
     # ── Thunderbird helpers ───────────────────────────────────────────────────
-    # external-editor-revived is the native-messaging host that lets the
-    # Thunderbird addon hand a composing draft to $EDITOR. We run TB as the
-    # org.mozilla.thunderbird flatpak; the AUR package would drag in system
-    # `thunderbird` as a hard dep, so we take it from nixpkgs here instead
-    # (the nix derivation has no mailer dep). The bridge wiring lives in
-    # run_onchange_after_deploy-tb-eer.sh.tmpl; it auto-detects the binary
-    # under ~/.nix-profile and the manifest gets relocated into the TB
-    # flatpak sandbox.
     external-editor-revived
 
     # ── Mail: ProtonMail Bridge ───────────────────────────────────────────────
-    # Headless IMAP/SMTP gateway (127.0.0.1:1143/1025) consumed by the
-    # Thunderbird flatpak and `git send-email`. No system coupling: it's a
-    # pure user daemon with a repo-owned user unit at
-    # dot_config/systemd/user/protonmail-bridge.service (run --noninteractive,
-    # pass-backed vault via PASSWORD_STORE_DIR). Replaces the AUR
-    # `protonmail-bridge-core`.
     protonmail-bridge
 
     # ── Secrets portal ────────────────────────────────────────────────────────
-    # Grimsteel's Rust org.freedesktop.secrets provider backed by pass. This is
-    # not nixpkgs' Python `pass-secret-service`; the repo-owned user unit at
-    # dot_config/systemd/user/pass-secret-service.service uses the Rust binary
-    # name and the PASSWORD_STORE_DIR drop-in.
     pass-secret-service-rust
 
     # ── Wayland session: bars, launchers, notifiers, daemons ──────────────────
-    # Pure user-session GUIs/daemons — no system unit, no D-Bus activation
-    # file under /usr/share/dbus-1, no login-manager session entry. The
-    # corresponding user-scope systemd units live under
-    # dot_config/systemd/user/ and reference these binaries by an absolute
-    # %h/.nix-profile/bin/<name> path. (Bare names do NOT work: systemd's
-    # ExecStart binary resolution does not use the imported/environment.d
-    # PATH of the --user manager, so a bare name fails with 203/EXEC even
-    # though `systemctl --user show-environment` shows the nix profile on
-    # PATH. The %h specifier expands to $HOME at unit-load time.)
     waybar
     mako
     fuzzel
-    wofi          # used by bemoji + mako-history.sh
+    wofi # used by bemoji + mako-history.sh
     swayidle
-    swayr         # auto-tiling + window switcher
-    inhibridge    # browser idle-inhibit bridge → systemd-inhibit
-    bemoji        # emoji picker (wofi backend)
-    wob           # volume/brightness OSD
+    swayr # auto-tiling + window switcher
+    inhibridge # browser idle-inhibit bridge → systemd-inhibit
+    bemoji # emoji picker (wofi backend)
+    wob # volume/brightness OSD
     poweralertd
 
     # ── Wayland: capture + clipboard + image viewing ─────────────────────────
@@ -140,70 +99,47 @@ in
     slurp
     wf-recorder
     wtype
-    wl-clipboard  # wl-copy + wl-paste
-    cliphist      # clipboard history (used by cliphist-{text,image} units)
+    wl-clipboard # wl-copy + wl-paste
+    cliphist # clipboard history (used by cliphist-{text,image} units)
 
     # ── Media control ────────────────────────────────────────────────────────
-    playerctl     # MPRIS over session bus
-    pulsemixer    # TUI for PipeWire/PulseAudio
-
-    # NOTE: GPU/OpenGL & EGL apps (ghostty, imv, wl-mirror) are
-    # intentionally NOT here — they stay on pacman/AUR. Nix-built GL apps on
-    # a non-NixOS host can't locate the system Mesa/DRI driver (the FHS
-    # /usr/lib drivers don't match nix's search paths) and fail at startup
-    # with "missing OpenGL context". On pacman they link against system Mesa.
-    # ghostty/imv/wl-mirror live in meta/base.txt. Sparrow is JavaFX-based and
-    # runs correctly from nix on the host.
+    playerctl # MPRIS over session bus
+    pulsemixer # TUI for PipeWire/PulseAudio
 
-    # ── General CLIs migrated off pacman ──────────────────────────────────────
+    # ── General CLIs ─────────────────────────────────────────────────────────
     qrencode
     torsocks
     lshw
     yt-dlp
     streamlink
-    xdg-utils     # xdg-open, used by yazi/linkhandler/OPENER
+    xdg-utils # xdg-open, used by yazi/linkhandler/OPENER
 
     # ── File sync ───────────────────────────────────────────────────────────────
-    # Package-only migration from pacman. The boot-time system service is the
-    # repo-owned syncthing@sommerfeld.service tracked in systemd-units/system.txt
-    # and backed by etc/systemd/system/syncthing@.service.
     syncthing
 
     # ── Work VPN ──────────────────────────────────────────────────────────────
-    # Check Point VPN client. The command-mode system service is repo-owned at
-    # etc/systemd/system/snx-rs.service and exposes the daemon that snxctl uses.
     snx-rs
 
     # ── Bitcoin wallet ───────────────────────────────────────────────────────
-    # Replaces the former AUR wallet package after host GUI + BitBox smoke
-    # testing.
     sparrow
 
     # ── Browser hardening ────────────────────────────────────────────────────
-    # Upstream Arkenfox user.js from nixpkgs, re-exposed under share/ so the
-    # chezmoi Firefox/LibreWolf deploy hook can render it with
-    # firefox/user-overrides.js into the Flatpak profile.
     arkenfox-userjs-profile
 
     # ── OCR ──────────────────────────────────────────────────────────────────
-    # Override merges eng + por language data into a single derivation,
-    # replacing three pacman packages (tesseract, tesseract-data-eng,
-    # tesseract-data-por).
-    (tesseract.override { enableLanguages = [ "eng" "por" ]; })
+    (tesseract.override {
+      enableLanguages = [
+        "eng"
+        "por"
+      ];
+    })
 
     # ── Speech-to-text (dictate script) ──────────────────────────────────────
-    # whisper.cpp with Vulkan acceleration. `mainProgram = "whisper-cli"`
-    # matches the binary the dictate script invokes. The base model below
-    # is a separate derivation so we can drop the AUR `whisper.cpp-model-base`.
     (whisper-cpp.override { vulkanSupport = true; })
     whisper-cpp-model-base
   ];
 
   # ── Smartcard (Yubikey) ────────────────────────────────────────────────────
-  # Nix's gnupg ships its own scdaemon. Delegate to the system pcscd
-  # service instead of letting nix's scdaemon open the USB device
-  # directly (which would race with pcscd). `pcsclite` provides the
-  # shared library at the path below and stays in `meta/base.txt`.
   home.file.".gnupg/scdaemon.conf".text = ''
     disable-ccid
     pcsc-driver /usr/lib/libpcsclite.so.1
diff --git a/nix/vm.nix b/nix/vm.nix
index 39bf52d..9e6352f 100644
--- a/nix/vm.nix
+++ b/nix/vm.nix
@@ -1,8 +1,6 @@
 { ... }:
 
-# VM-only Home-Manager profile (Ubuntu remote-dev box). This installs the
-# shared tool profile and VM session variables only; dotfile deployment is
-# owned by chezmoi, matching the Arch host.
+# VM-only Home-Manager package profile.
 {
   imports = [ ./common.nix ];
 
@@ -10,14 +8,8 @@
   home.homeDirectory = builtins.getEnv "HOME";
 
   home.sessionVariables = {
-    # Ubuntu 20.04-derived hosts still default to cgroups v1; podman 5
-    # warns on every invocation. Flipping to v2 is a host-level reboot
-    # and only matters for --memory/--cpus, so silence the warning.
-    # (Arch host is on cgroups v2, so this isn't set in common.nix.)
     PODMAN_IGNORE_CGROUPSV1_WARNING = "1";
   };
 
-  # No extra packages — the rootless podman stack now lives in
-  # `common.nix` so the host and VM share the same nix-pinned versions.
   home.packages = [ ];
 }