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/identity/authentik.nix

@@ -1,30 +1,22 @@
 { config, pkgs, inputs, ... }:
 
-# Authentik — self-hosted identity/OIDC provider.
+# Authentik — self-hosted identity/OIDC provider. Replaced Zitadel because
+# nixpkgs is stuck on 2.71 (no login-v2 split) with a forward-only db
+# migration; authentik-nix tracks upstream closely instead.
 #
-# Replaced Zitadel: nixpkgs only carries Zitadel 2.71 (no login-v2 split, and
-# a v3/v4 database migrates forward only, so an existing instance can't be
-# moved onto it). authentik-nix tracks upstream closely instead.
+# The upstream module owns postgres and its unit ordering, and needs no redis
+# (channels/cache run on postgres). TLS terminates at Caddy; every listener
+# below is pinned to loopback since only tailscale0 is trusted.
 #
-# The upstream module owns postgres (createDatabase) AND orders the units
-# against postgresql.target, so no manual After= is needed here. No redis —
-# recent authentik runs channels/cache on postgres.
-#
-# TLS terminates at Caddy; every listener is pinned to loopback below so
-# nothing is reachable from the tailnet (hosts trust tailscale0).
-#
-# Needs, wired via sops in the host's secrets.nix: an environmentFile carrying
-#   - AUTHENTIK_SECRET_KEY          (`openssl rand -base64 60`) — signs sessions
-#   - AUTHENTIK_BOOTSTRAP_PASSWORD  first-run akadmin password
-# systemd reads EnvironmentFile as root before dropping to the service's
-# DynamicUser, so the sops default root:root 0400 is correct — do NOT set
-# `owner` on it the way the headplane secrets need.
+# Needs an environmentFile from sops (host's secrets.nix) carrying
+# AUTHENTIK_SECRET_KEY and AUTHENTIK_BOOTSTRAP_PASSWORD. Keep it root:root
+# 0400 (systemd reads it as root before dropping to DynamicUser) — don't set
+# `owner` the way headplane's secrets need.
 {
   imports = [ inputs.authentik-nix.nixosModules.default ];
 
   # Pinned explicitly: the default tracks system.stateVersion, so editing that
-  # line would silently demand a pg_upgrade of the identity store. Bump this
-  # deliberately, with a dump in hand.
+  # would silently demand a pg_upgrade of the identity store.
   services.postgresql.package = pkgs.postgresql_17;
 
   services.authentik = {