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

hosts/terra/configuration.nix

@@ -44,17 +44,9 @@ in
   # https://nix.dev/permalink/stub-ld ----
   programs.nix-ld.enable = true;
 
-  # The default set above is deliberately minimal and carries no X11,
-  # freetype, wayland or xkbcommon, so a prebuilt *graphical* binary dies
-  # before it draws anything. JetBrains IDEs installed through Toolbox are the
-  # case that surfaced this: their bundled JBR aborts with `libX11.so.6:
-  # cannot open shared object file` unless the Toolbox GUI — itself an FHS
-  # wrapper — is what launches them, which makes them unusable from a terminal
-  # or from a per-repo devShell. These are the libraries `ldd` reports missing
-  # across a JBR's own .so files, plus the three it resolves by dlopen rather
-  # than DT_NEEDED: fontconfig for font discovery, libGL, and libsecret for
-  # the credential store. Definitions merge, so this adds to the module's base
-  # list rather than replacing it (zlib is already there).
+  # JetBrains IDEs installed via Toolbox bundle a JBR that aborts with
+  # `libX11.so.6: cannot open shared object file` under the default (X11-less)
+  # nix-ld set. Additive — merges with the module's own base list (zlib etc).
   programs.nix-ld.libraries = with pkgs; [
     freetype
     fontconfig
@@ -72,28 +64,19 @@ in
     libxinerama
     libxcb
 
-    # CLion Nova's C++ backend (the clion-radler plugin) is a .NET 10
-    # application bundling its own runtime, and .NET refuses to start
-    # without ICU: libSystem.Globalization.Native.so dlopens libicuuc.so
-    # and libicui18n.so, and failing that the IDE reports "Couldn't find a
-    # valid ICU package installed on the system" and comes up degraded.
+    # CLion Nova's C++ backend is a .NET 10 app that needs ICU or reports
+    # "Couldn't find a valid ICU package installed on the system".
     icu
   ];
 
-  # ---- envfs: serves /bin and /usr/bin from the calling process's PATH ----
-  # NixOS ships only /bin/sh, but plenty of third-party tooling writes scripts
-  # with a hardcoded interpreter. JetBrains Toolbox is the standing example:
-  # it generates ~/.local/share/JetBrains/Toolbox/scripts/{clion,rider,...}
-  # with `#!/bin/bash`, so every one of those shims fails with `bad
-  # interpreter` in any shell. envfs resolves such shebangs against PATH,
-  # which fixes them all at once instead of per-IDE wrappers.
+  # NixOS only ships /bin/sh; envfs serves /bin and /usr/bin from PATH so
+  # third-party scripts hardcoding `#!/bin/bash` (e.g. JetBrains Toolbox's
+  # generated launchers) still resolve.
   services.envfs.enable = true;
 
   # ---- home-manager (user-level config for darman) ----
-  # Base settings (useGlobalPkgs/useUserPackages/backupFileExtension) and the
-  # shared zsh baseline now live in common.nix + home/common.nix, applied to
-  # every host. This just layers terra's desktop/dev-specific profile on top
-  # — home-manager.users.darman.imports merges additively across modules.
+  # Base settings + shared zsh baseline live in common.nix + home/common.nix
+  # (every host); this layers terra's desktop profile on top (imports merge).
   home-manager.extraSpecialArgs = { inherit unstable inputs; };
   home-manager.users.darman.imports = [ ./home.nix ];
 
@@ -102,71 +85,47 @@ in
   boot.loader.efi.canTouchEfiVariables = true;
   hardware.cpu.amd.updateMicrocode = true;
 
-  # mercury (aarch64) is built/flashed from here. Without this, `nix build`
-  # for it dies with "platform mismatch" — no qemu binfmt handler registered
-  # and aarch64-linux missing from nix.settings.extra-platforms. This module
-  # sets up both (see CLAUDE.md's aarch64 gotcha).
+  # Lets `nix build` target mercury (aarch64) from here — see CLAUDE.md's
+  # aarch64 gotcha.
   boot.binfmt.emulatedSystems = [ "aarch64-linux" ];
 
   # ---- GPU (Radeon RX 6800 XT / Navi 21) ----
   hardware.enableRedistributableFirmware = true;
   boot.initrd.kernelModules = [ "amdgpu" ];
 
-  # /dev/dri/renderD128 is root:render 0660, so rootless podman containers can
-  # only reach the GPU if the *host* user is in render. Needed by the Vulkan
-  # whisper.cpp/llama.cpp containers in ~/Data/Dev/repos/content-trigger-scanner.
+  # /dev/dri/renderD128 is root:render 0660 — host user needs render group for
+  # rootless podman GPU containers (Vulkan whisper.cpp/llama.cpp).
   users.users.darman.extraGroups = [ "render" "video" ];
 
   # ---- ollama (local LLM server, ROCm on the 6800 XT) ----
-  # Navi 21 is gfx1030 — officially supported by ROCm, so no
-  # rocmOverrideGfx/HSA_OVERRIDE_GFX_VERSION needed (that's for gpus ROCm
-  # doesn't recognize, e.g. RDNA1/gfx101x). The upstream module runs the
-  # service under DynamicUser with SupplementaryGroups=["render"] and
-  # DeviceAllow for char-kfd/char-drm/char-fb already, so unlike jellyfin's
-  # static user it needs no extraGroups wiring here.
+  # Navi 21 (gfx1030) is officially ROCm-supported, so no
+  # HSA_OVERRIDE_GFX_VERSION needed. Upstream module already runs under
+  # DynamicUser with render/kfd/drm access wired, unlike jellyfin's static user.
   services.ollama = {
     enable = true;
     package = pkgs.ollama-rocm;
-    # keep in sync with services/desktop/librechat.nix's endpoints.custom
-    # default model — LibreChat's config schema needs a non-empty default
-    # even though fetch=true replaces it with whatever's actually pulled.
-    # gemma4:12b: general chat/coding daily driver, fits fully in 16G VRAM —
-    # also doubles as the memory-extraction agent (see librechat.nix): a
-    # 3b model (llama3.2:3b, dropped) couldn't reliably tell the user's
-    # stated facts apart from its own boilerplate, e.g. saving "I am an AI
-    # assistant with tool calling capabilities" as the user's personal_info
-    # after "Hi I'm Erik Simon". Reusing gemma4:12b for both roles also means
-    # no second model needs to swap into VRAM while it's already the active
-    # chat model.
-    # qwen3.6:35b-a3b: MoE (3B active/36B total), ~24GB Q4_K_M — doesn't fit
-    # in VRAM alone, so ollama offloads the inactive experts to CPU RAM.
-    # Sparse activation makes that far less painful than it'd be for a dense
-    # model this size, but still expect it to run slower than the two above.
-    # VladimirGav/qwen3.8-27B-14GB-IQ4: dense 27B at IQ4, ~14GB of weights —
-    # nominally fits the 6800 XT's 16G, but that leaves only ~2G for the KV
-    # cache and the compositor, so expect partial CPU offload as context grows
-    # (OLLAMA_CONTEXT_LENGTH below applies to every model on this server).
+    # keep default model in sync with services/desktop/librechat.nix's
+    # endpoints.custom default (its schema needs a non-empty value even
+    # though fetch=true overrides it).
+    # gemma4:12b: daily-driver chat/coding model, fits fully in 16G VRAM; also
+    # doubles as LibreChat's memory-extraction agent (librechat.nix) since a
+    # smaller model confused the user's stated facts with its own boilerplate.
+    # qwen3.6:35b-a3b: MoE (3B active/36B total, ~24GB Q4_K_M) — doesn't fit
+    # in VRAM alone, so ollama offloads inactive experts to CPU RAM; sparsity
+    # makes that less painful than for a dense model this size, but still slower.
+    # VladimirGav/qwen3.8-27B-14GB-IQ4: dense 27B at IQ4 (~14GB) — nominally
+    # fits the 16G card but leaves little headroom, so expect partial CPU
+    # offload as context grows.
     loadModels = [
       "gemma4:12b"
       "qwen3.6:35b-a3b"
       "VladimirGav/qwen3.8-27B-14GB-IQ4"
     ];
-    # Ollama truncates context far below the model's real window unless
-    # told otherwise (the OpenAI-compat /v1 route it's reached through has
-    # no way to set this per-request). 131072 chosen as the practical
-    # ceiling after load-testing with real prompts, not just idle
-    # `ollama ps` checks:
-    # 32768 (31.6k-token prompt) and 65536 (40.8k-token prompt) both stayed
-    # 100% GPU with VRAM barely moving (~10.1G / ~10.67G of 16G) — KV cache
-    # cost barely grows with context, likely sliding-window/local attention
-    # on most of gemma4:12b's layers. At 131072 that stopped being true: a
-    # ~108k-token prompt pushed VRAM to ~11.4G/16G (still 100% GPU, no CPU
-    # spillover, negligible GTT) but with visibly shrinking headroom, and
-    # prefill throughput measurably dropped (~490 -> ~460 tok/s) over just
-    # the last 13k tokens — filling the full window would take minutes of
-    # pure prompt processing. Stopped here rather than push further: next
-    # doubling would risk CPU spillover under any concurrent GPU load
-    # (desktop compositor, jellyfin transcode) for diminishing benefit.
+    # Ollama truncates context far below a model's real window unless told
+    # otherwise. 131072 is the practical ceiling from load-testing: VRAM stays
+    # 100% GPU with no CPU spillover up to here, but headroom and prefill
+    # throughput both degrade near the top — going higher risks CPU spillover
+    # under concurrent GPU load (compositor, jellyfin transcode) for little gain.
     environmentVariables.OLLAMA_CONTEXT_LENGTH = "131072";
   };