Skip to content

Workstation reference

Each entry explains why one config decision exists. If a why is wrong or a decision is missing, fix the page.

Repository

Stow tree with --no-folding

Where What Why Breaks if
AGENTS.md, scripts/bin/sh/dotfiles-stow Each top-level folder is a stow package that mirrors $HOME. dotfiles-stow runs stow -Sv --no-folding for base, editors, tui, x11, systemd, autokey, _private. Every dotfile lives in one repo while $HOME holds symlinks. --no-folding makes one symlink per file instead of one per directory. Separate packages can contribute to the same target directory, for example ~/.config, without overwriting each other. If raw stow <pkg> runs or a package folder is renamed, existing $HOME symlinks point at the old paths. A re-stow restores them.

scripts stowed as a whole directory

Where What Why Breaks if
scripts/bin/sh, scripts/bin/py, stow -Sv scripts in dotfiles-stow stow -Sv scripts links scripts/bin to ~/bin as a directory. A new script needs no re-stow, and ~/bin stays clean of hundreds of symlinks. If a script is added outside scripts/bin/sh or scripts/bin/py, it never lands on $PATH.

_private excluded from git and syncthing

Where What Why Breaks if
_private/, .gitignore, .stignore _private holds host-private config and never gets committed or synced. Some machines carry secrets and quirks that must not propagate to other hosts. If a file leaks into _private, it gets committed and synced everywhere.

Shell

set -euo pipefail in every script

Where What Why Breaks if
Every script in scripts/bin/sh (AGENTS.md rule) set -euo pipefail exits on any failing command, unset variable, or failing element of a pipeline. Scripts fail loudly instead of continuing half-done. This matters when they touch $HOME or system state. If the line is dropped, a failed command lets the script continue with broken assumptions, for example a disconnected monitor.

#!/usr/bin/env bash shebang

Where What Why Breaks if
AGENTS.md rule, normalized across scripts/bin/sh #!/usr/bin/env bash resolves bash through $PATH. The shebang works on systems where bash does not sit at /bin/bash. If a script uses the #!/bin/bash shebang, the script fails on systems without /bin/bash.

GPG

gpg-agent cache and SSH support

Where What Why Breaks if
base/.gnupg/gpg-agent.conf and ~/.gnupg/gpg-agent.conf default-cache-ttl 21600 and max-cache-ttl 43200 set the GPG passphrase cache window. The -ssh variants set the same values for SSH, with enable-ssh-support and pinentry-qt. default-cache-ttl 21600 keeps the passphrase cached during a long work session. max-cache-ttl 43200 forces expiry, so keys are not left loaded overnight. If enable-ssh-support is disabled, ssh stops using the agent. Lower TTLs cause repeated prompts mid-session.

Display

$mod+x opens the layout picker

Where What Why Breaks if
x11/.config/i3/config:159 and ~/.config/i3/config, scripts/bin/sh/monitor-selection monitor-selection lists ~/.screenlayout/*.sh in rofi and calls monitor-init-layout with the selection. This switches layouts without touching the i3 config or reopening arandr. If monitor-selection drops off $PATH or another binding reuses $mod+x, the picker stops working.

polybar is run by monitor-init-layout, not i3

Where What Why Breaks if
x11/.config/i3/config:354 (comment) and ~/.config/i3/config, scripts/bin/sh/monitor-init-layout i3 does not run polybar. monitor-init-layout runs it on every layout load. The bar must re-place itself for the current output geometry. If exec polybar-launcher is added to i3, polybar runs before the layout applies and can land on the wrong output.