docs: condense comments across the repo

Comments had drifted into multi-paragraph narrative (git commit
lineage, debugging stories, restated code) in several hot spots
(scripts/deploy, hermes-agent.nix, flake.nix, gitea.nix, headscale.nix).
Trim every comment to its load-bearing "why" — gotchas, safety
warnings, and non-obvious rationale survive verbatim in substance,
just tightened to 1-2 sentences; historical narrative and anything
already covered in CLAUDE.md is cut. No code/logic changed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJqEmY1y3AYX3JoX4Y6b21

services/network/pihole.nix

@@ -53,17 +53,11 @@ in
     };
   };
 
-  # Bind-mount source must exist (podman won't create it), and it must be
-  # owned by 1000 — the `pihole` user FTL drops to after the entrypoint's root
-  # phase. Podman here is rootful with no userns remapping, so that number is
-  # the same inside and out (on the host it collides with darman, harmlessly).
-  #
-  # Ownership of gravity.db alone is not enough: sqlite creates a sibling
-  # gravity.db-journal for every write transaction, so FTL needs to CREATE
-  # files in this directory. Root-owned, it fails with
-  #   open(/etc/pihole/gravity.db-journal) - (14)
-  #   attempt to write a readonly database
-  # which reads like a corrupt or read-only database and is neither.
+  # Bind-mount source must exist (podman won't create it) and be owned by 1000,
+  # the `pihole` user FTL drops to (rootful podman, no userns remapping, so the
+  # uid is the same inside and out). Must be the whole DIRECTORY, not just
+  # gravity.db — sqlite needs to create a sibling gravity.db-journal per write,
+  # and a root-owned dir makes that fail with a misleading "readonly database".
   systemd.tmpfiles.rules = [ "d /var/lib/pihole 0750 1000 1000 -" ];
 
   # Seed the adlists above into gravity. `INSERT OR IGNORE` keyed on the URL

services/network/samba.nix

@@ -22,14 +22,13 @@
     };
   };
 
-  # Samba keeps its own NTLM password DB, separate from the system password;
-  # `services.samba` never sets it, so logins fail until provisioned. Runs
-  # AFTER samba-smbd so its state dir exists — an activation script runs too
-  # early and smbpasswd fails to init the passdb. Reads a single-line
-  # password from the first file that exists:
+  # Samba keeps its own NTLM password DB, separate from the system password —
+  # `services.samba` never sets it, and this runs as a service (not an
+  # activation script, which fires too early for smbpasswd's passdb) after
+  # samba-smbd. Reads a single-line password from the first existing file,
+  # feeding it twice since smbpasswd prompts new+confirm:
   #   Real host: /run/secrets/samba_password  (sops-nix, see secrets.nix)
   #   VM test:   /etc/samba/smb-password       (plaintext, see vm.nix)
-  # smbpasswd prompts new + confirm, so the value is fed twice.
   systemd.services.samba-smbpasswd = {
     description = "Provision Samba password for darman";
     after = [ "samba-smbd.service" ];

services/network/unbound.nix

@@ -1,8 +1,8 @@
 { ... }:
 
-# Local recursive DNS resolver (privacy + DNSSEC). Your adblock DNS
-# (pihole/AdGuard) forwards to this instead of a public upstream.
-# Listens on 127.0.0.1:5335 — point the adblock engine's upstream there:
+# Local recursive DNS resolver (privacy + DNSSEC) that the adblock DNS
+# (pihole/AdGuard) forwards to instead of a public upstream — listens on
+# 127.0.0.1:5335, so point the adblock engine's upstream there:
 #   AdGuard:  dns.upstream_dns = [ "127.0.0.1:5335" ];
 #   pihole:   upstream = "127.0.0.1#5335";
 {