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/dev/obsidian-livesync.nix

@@ -1,66 +1,50 @@
 { config, ... }:
 
-# CouchDB, tuned as the backend for Obsidian Self-hosted LiveSync
-# (vrtmrz/obsidian-livesync). The plugin replicates the vault into CouchDB
-# chunk-by-chunk over PouchDB's replication protocol, so this is a plain
-# CouchDB 3 node — nothing Obsidian-specific runs here.
+# Plain CouchDB 3 node, tuned as the backend for Obsidian Self-hosted LiveSync
+# (vrtmrz/obsidian-livesync), which replicates the vault into it via PouchDB.
 #
-# Published PUBLICLY as https://notes.mgaction.town via neptun's caddy (see
-# hosts/neptun/configuration.nix), because Obsidian's mobile apps refuse
-# cleartext HTTP and jupiter's *.jupiter.sol names cannot get a real cert.
-# That makes the settings below security-relevant, not cosmetic:
+# Published PUBLICLY as https://notes.mgaction.town via neptun's caddy, since
+# Obsidian's mobile apps refuse cleartext HTTP and jupiter's *.jupiter.sol
+# names can't get a real cert — so the settings below are security-relevant:
+#   - `require_valid_user` in both [chttpd] and [chttpd_auth], else CouchDB
+#     answers unauthenticated GETs on the open internet.
+#   - neptun's vhost allowlists only the plugin's endpoints; Fauxton and
+#     cluster/config are reachable only over the tailnet.
+#   - Turn on the plugin's end-to-end encryption (+ "Obfuscate Properties"),
+#     so this server only ever holds ciphertext — what makes a
+#     publicly-reachable credentialed database an acceptable trade.
 #
-#   - `require_valid_user` in BOTH [chttpd] and [chttpd_auth]: without it
-#     CouchDB answers unauthenticated GETs on the open internet.
-#   - neptun's vhost allowlists only the endpoints the plugin uses, so Fauxton
-#     (/_utils) and the cluster/config endpoints are not reachable from
-#     outside at all — reach them over the tailnet instead.
-#   - Turn ON end-to-end encryption in the plugin (Settings → Remote Database
-#     → End-to-End Encryption, plus "Obfuscate Properties", which covers the
-#     paths and timestamps that E2EE alone leaves readable). Then this server
-#     only ever holds ciphertext, which is what makes a publicly-reachable
-#     credentialed database an acceptable trade rather than a bad one.
-#
-#     Its passphrase is a SEPARATE secret from couchdb_admin_password below —
-#     deliberately, and it must stay that way. The couchdb password
-#     authenticates to this server and is stored here (hashed) and in
-#     secrets/jupiter.yaml; the E2EE passphrase never leaves the Obsidian
-#     clients and CouchDB has no idea it exists. Reusing one string for both
-#     hands whoever obtains that credential the decryption key as well, which
-#     is precisely the failure E2EE is here to prevent. The passphrase is
-#     therefore NOT in sops (nothing on this host consumes it) — it lives in
-#     the HomeLab Proton Pass vault, with the deploy credentials.
-#
-#     Losing it costs the remote database, not the notes: wipe it and
+#     Its passphrase must stay a SEPARATE secret from couchdb_admin_password:
+#     the CouchDB password is stored here and in secrets/jupiter.yaml, while
+#     the E2EE passphrase never leaves the clients (kept in the HomeLab Proton
+#     Pass vault, not sops) — reusing one string for both would hand the
+#     decryption key to whoever gets the CouchDB credential. Losing the
+#     passphrase costs the remote database, not the notes: wipe and
 #     re-initialize from a device that still holds the plaintext vault.
 {
   services.couchdb = {
     enable = true;
 
-    # Listens on all interfaces, same reasoning as immich: :5984 is NOT opened
-    # in the firewall, so it is reachable over tailscale0 (trusted in
-    # common.nix) and localhost only. That is the path neptun's caddy takes.
+    # Listens on all interfaces, but :5984 is not opened in the firewall, so
+    # it's reachable only over tailscale0 (trusted) and localhost — the path
+    # neptun's caddy takes.
     bindAddress = "0.0.0.0";
     port = 5984;
 
     # The vault database is the ONLY copy of the notes once LiveSync is the
-    # source of truth, so it belongs on the array, not the 29G eMMC. All three
-    # of these default under /var/lib/couchdb and have to move together —
-    # configFile especially, since CouchDB writes to it at runtime (below).
+    # source of truth, so it belongs on the array, not the 29G eMMC — all
+    # three default under /var/lib/couchdb and must move together.
     databaseDir = "/mnt/data/AppData/couchdb";
     viewIndexDir = "/mnt/data/AppData/couchdb";
     configFile = "/mnt/data/AppData/couchdb/local.ini";
 
-    # The admin password, as an [admins] ini fragment from sops.
-    # services.couchdb.adminPass would render it into the world-readable
-    # store; extraConfigFiles is the module's own documented hook for this
-    # (hosts/jupiter/secrets.nix renders the template).
+    # [admins] ini fragment from sops; services.couchdb.adminPass would render
+    # into the world-readable store instead.
     #
-    # ⚠️ CouchDB hashes a plaintext admin password at startup and persists the
-    # hash to the LAST, writable file in its ini chain — local.ini above,
-    # which then takes precedence over this fragment. So changing the sops
-    # value alone does NOT rotate the password: delete the `[admins]` line
-    # from /mnt/data/AppData/couchdb/local.ini and restart as well.
+    # ⚠️ CouchDB hashes the password at startup and persists it to local.ini
+    # (above), which then takes precedence — so changing the sops value alone
+    # does NOT rotate it. Also delete the `[admins]` line from
+    # /mnt/data/AppData/couchdb/local.ini and restart.
     extraConfigFiles = [ config.sops.templates."couchdb-admins.ini".path ];
 
     # Values taken from LiveSync's own CouchDB setup documentation; the plugin