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/media/immich.nix

@@ -1,30 +1,22 @@
 { config, pkgs, inputs, ... }:
 
-# Immich photo/video library. Native nixpkgs module (not the upstream compose
-# stack) — it owns its own postgres (with the pgvector + vectorchord extensions
-# it needs for search) and a unix-socket redis, so nothing else is required here.
+# Immich photo/video library. Native nixpkgs module, not the upstream compose
+# stack — it owns its own postgres (pgvector + vectorchord) and a unix-socket redis.
 #
-# Storage: everything lives under /mnt/data/AppData/immich, which is the media
-# store MIGRATED from the old ZimaOS/CasaOS install's UPLOAD_LOCATION
-# (/mnt/data/Immich/upload — same layout: library/ upload/ thumbs/
-# encoded-video/ profile/ backups/). See scripts/immich-import-legacy-db for the
-# matching database import. The postgres cluster itself stays on the OS disk.
+# Storage lives under /mnt/data/AppData/immich, migrated from the old ZimaOS/CasaOS
+# UPLOAD_LOCATION (same subfolder layout); see scripts/immich-import-legacy-db for
+# the matching DB import. The postgres cluster itself stays on the OS disk.
 #
 # ⚠️ The immich DB is the only copy of albums/faces/dates — the files alone
 # can't rebuild it. It joins the other unbacked databases on this network.
 let
-  # The PACKAGE comes from nixpkgs-unstable (3.0.3); the MODULE comes from the
-  # 26.05 pin (which ships 2.7.5). That combination is safe because the two
-  # module files are byte-identical — verified by diffing them at the revisions
-  # in flake.lock. RE-CHECK THAT DIFF on any input bump:
+  # Package pinned to nixpkgs-unstable (3.0.3) while the module stays on the 26.05
+  # pin (2.7.5) — safe only because the two module files are byte-identical
+  # (verified by diff; re-check on any input bump). Needed because immich's
+  # migrations are forward-only and jupiter's imported DB was last written by
+  # 3.0.0, which 2.7.5 refuses to start against; drop once the pin ships >= 3.0.0.
   #   diff <(nixpkgs)/nixos/modules/services/web-apps/immich.nix \
   #        <(unstable)/nixos/modules/services/web-apps/immich.nix
-  #
-  # Why: jupiter's imported database was last written by immich 3.0.0, and
-  # immich runs its migrations forward only — 2.7.5 refuses to start against it
-  # with "corrupted migrations: previously executed migration
-  # 1776217577402-DropAuditTable is missing". Drop this override once nixos-26.11
-  # (or whatever the pin becomes) ships >= 3.0.0.
   unstable = import inputs.nixpkgs-unstable {
     inherit (pkgs.stdenv.hostPlatform) system;
   };
@@ -42,27 +34,20 @@ in
     mediaLocation = "/mnt/data/AppData/immich";
     machine-learning.enable = true;
 
-    # ⚠️ Setting `settings` at all switches immich to IMMICH_CONFIG_FILE, and
-    # that is ALL-OR-NOTHING (dist/utils/config.js: the config is
-    # `configFile ? loadFromFile(...) : metadataRepo.get(SystemConfig)` — the
-    # database copy is IGNORED, not merged). Two consequences:
-    #   1. Anything not declared here falls back to immich's DEFAULTS, not to
-    #      whatever the admin UI had. The old settings stay in the
-    #      system_metadata table, so deleting this block restores them.
-    #   2. The admin settings UI goes read-only — saving throws "Cannot update
-    #      configuration while IMMICH_CONFIG_FILE is in use". Change settings
-    #      HERE and redeploy.
-    # An unknown/misspelled key is a HARD startup failure under a config file
-    # (the same code path only logs a warning without one), so keys below are
-    # taken verbatim from `defaults` in immich's dist/config.js.
+    # ⚠️ Setting `settings` at all switches immich to IMMICH_CONFIG_FILE mode,
+    # which is all-or-nothing: undeclared keys fall back to immich's defaults, not
+    # the admin UI's saved values (which stay in system_metadata and return if
+    # this block is deleted), and the admin settings UI goes read-only. An
+    # unknown/misspelled key is a hard startup failure here (just a warning
+    # without a config file), so keys are copied verbatim from `defaults` in
+    # immich's dist/config.js.
     settings = {
       server.externalDomain = "https://immich.mgaction.town";
       newVersionCheck.enabled = false;   # nixpkgs pins the version, not immich
 
-      # OIDC via Authentik on neptun. The Authentik application/provider is
-      # created BY HAND in its UI — same as headscale's and headplane's, which
-      # are also separate apps (hosts/neptun/secrets.nix). Only the client
-      # secret is managed here.
+      # OIDC via Authentik on neptun; the application/provider is created by hand
+      # in its UI (like headscale's and headplane's, separate apps) — only the
+      # client secret is managed here (hosts/neptun/secrets.nix).
       oauth = {
         enabled = true;
         # Authentik's per-application issuer. Trailing slash matters: immich
@@ -76,24 +61,18 @@ in
         clientSecret._secret = config.sops.secrets.immich_oauth_client_secret.path;
         scope = "openid email profile";
         buttonText = "Login with Authentik";
-        # Existing accounts (the 2 imported users) keep working: matching is by
-        # email, so an Authentik user with the same address adopts that account
-        # rather than creating a second one.
+        # Matches by email, so the 2 imported users adopt their Authentik account
+        # instead of getting a duplicate.
         autoRegister = true;
         # Leave the password form reachable — autoLaunch would bounce straight
         # to Authentik, locking everyone out if the OIDC app is misconfigured.
         autoLaunch = false;
-        # Land back on immich's own login page after logout. Without this,
-        # immich falls back to the IdP's discovered end_session_endpoint
-        # (auth.service.js:320-326) and logout dumps you on Authentik's
-        # "you've been logged out" page instead. Must be an ABSOLUTE url —
-        # the config schema rejects a relative path — and mirrors immich's
-        # internal LOGIN_URL, including autoLaunch=0.
-        #
-        # Note this ends the IMMICH session only; the Authentik SSO session
-        # survives, so the next "Login with Authentik" click signs straight
-        # back in without a credential prompt. To end both, drop this line and
-        # let the IdP endpoint take over again.
+        # Without this, immich falls back to the IdP's discovered
+        # end_session_endpoint and logout dumps you on Authentik's own page
+        # instead of back here — must be an absolute url, mirroring immich's
+        # internal LOGIN_URL. This ends the immich session only; the Authentik
+        # SSO session survives, so the next login skips the credential prompt —
+        # drop this line to end both.
         endSessionEndpoint = "https://auth.mgaction.town/application/o/immich/end-session?post_logout_redirect_url=https://immich.mgaction.town";
         # The mobile app can't follow a browser redirect back to a custom
         # scheme through Authentik, so immich bounces it via this endpoint.
@@ -101,28 +80,24 @@ in
         mobileRedirectUri = "https://immich.mgaction.town/api/oauth/mobile-redirect";
       };
     };
-    # Hardware transcoding would need the iGPU passed in explicitly, e.g.
-    # accelerationDevices = [ "/dev/dri/renderD128" ]; the default [ ] means
-    # PrivateDevices=yes and CPU-only transcode. The ZimaBlade's Celeron does
-    # this slowly but it only runs on upload.
+    # Hardware transcoding needs accelerationDevices set explicitly (e.g.
+    # "/dev/dri/renderD128"); default CPU-only transcode is slow on the
+    # ZimaBlade's Celeron but only runs on upload.
   };
 
-  # /mnt/data/AppData is drwx--x--- darman:users — immich needs group "users"
-  # just to TRAVERSE into its own media dir. The dir itself stays 0700
-  # immich:immich (the module's tmpfiles rule re-asserts that every rebuild,
-  # and UMask=0077 keeps new files private), so this grants nothing else.
+  # /mnt/data/AppData is drwx--x--- darman:users; immich only needs group "users"
+  # to traverse into it — the dir itself stays 0700 immich:immich (tmpfiles +
+  # UMask=0077 reassert that), so this grants nothing else.
   users.users.immich.extraGroups = [ "users" ];
 
-  # mediaLocation is outside /var/lib, so the module won't create it — its own
-  # tmpfiles entry only ADJUSTS an existing dir. Harmless no-op after the
-  # legacy import, which puts the real store here.
+  # mediaLocation is outside /var/lib, so the module won't create it — this rule
+  # only adjusts perms on the dir the legacy import already created.
   systemd.tmpfiles.rules = [
     "d /mnt/data/AppData/immich 0700 immich immich -"
   ];
 
-  # The unit's automatic RequiresMountsFor covers /run/immich and /var/lib/immich
-  # only — nothing points it at mediaLocation. Without this immich starts with
-  # the array missing and writes uploaded photos onto the 29G eMMC, into a
-  # directory that becomes invisible the moment /mnt/data mounts over it.
+  # The unit's automatic RequiresMountsFor doesn't cover mediaLocation — without
+  # this, immich starts before /mnt/data mounts and writes uploads onto the 29G
+  # eMMC, invisibly, under the future mountpoint.
   systemd.services.immich-server.unitConfig.RequiresMountsFor = [ "/mnt/data" ];
 }