chore: log dotfiles-separation progress and file processed handoffs

1 files changed, 37 insertions, 0 deletions

diff --git a/assets/outbox/2026-05-22-archangel-ssh-auth-sock-finalize-handoff.org b/assets/outbox/2026-05-22-archangel-ssh-auth-sock-finalize-handoff.org
new file mode 100644
index 0000000..5a090b8
--- /dev/null
+++ b/assets/outbox/2026-05-22-archangel-ssh-auth-sock-finalize-handoff.org
@@ -0,0 +1,37 @@
+#+TITLE: Finalize the machine-wide SSH_AUTH_SOCK fix (from archangel)
+#+DATE: 2026-05-22
+
+* Why this is here
+
+A machine-wide =SSH_AUTH_SOCK= change was started from an *archangel* session and lives in archsetup's =common= stow package, still uncommitted. The goal: every shell and session on a box — login shells, GUI apps, cron, and Claude's non-interactive Bash-tool shells — reaches gpg-agent for SSH keys with no per-script effort, so =ssh= / =ssh-add= to external hosts (e.g. truenas) work anywhere. gpg-agent already has =enable-ssh-support= (per-DE =gpg-agent.conf=); this just points =SSH_AUTH_SOCK= at its fixed socket.
+
+* Current uncommitted state (dotfiles/common)
+
+- =.config/environment.d/envvars.conf= — added =SSH_AUTH_SOCK=${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh= (modified, tracked).
+- =.zshenv= — *new file*, exports the same (untracked).
+- =~/.zshenv= was symlinked into the stow tree this session to activate it immediately; confirm stow owns it on the next =make restow=.
+
+* The decision to make: one mechanism or two
+
+- *1a — environment.d only.* Matches archsetup's existing convention (env vars already live in envvars.conf), one clean mechanism, no new dotfile type. Drop the =.zshenv=.
+- *1b — environment.d + .zshenv.* Belt-and-suspenders: environment.d covers the systemd/GUI session, =.zshenv= guarantees *every* zsh including non-interactive ones (cron, tooling). Cost: a =.zshenv= convention the repo didn't have, and apparent redundancy.
+
+** How to decide (empirically — couldn't be isolated from the archangel session)
+
+The original problem was that *non-interactive* shells (Claude's Bash tool) didn't inherit =SSH_AUTH_SOCK=. The =.zshenv= path was *verified* to fix that; =environment.d=-alone was *not* isolated, because testing it needs the change committed/stowed and a fresh login.
+
+After =make restow= + re-login, in a *non-interactive* shell check whether environment.d alone propagated:
+#+begin_src bash
+zsh -fc 'echo "${SSH_AUTH_SOCK:-UNSET}"'   # -f skips .zshenv, so this shows environment.d-only reach
+#+end_src
+- Prints the gpg-agent socket → environment.d reaches non-interactive shells → go *1a*, delete =dotfiles/common/.zshenv= and the =~/.zshenv= symlink.
+- Prints =UNSET= → environment.d doesn't reach them → keep *1b*.
+
+* Steps
+
+1. =make restow <de>= so stow owns the symlink(s).
+2. Re-login (environment.d reloads at session start).
+3. Run the reachability check above; pick 1a or 1b.
+4. Commit the dotfile change(s). Conventional-commit, no AI attribution. Suggested subject: =feat(dotfiles): route SSH_AUTH_SOCK through gpg-agent=.
+
+Nothing personal-tooling/.ai is referenced in the dotfiles, so they're clean to commit as-is.