gnu-plus-dotfiles/README.md

# gnu-plus-dotfiles

Chezmoi-managed dotfiles synced across all your linux boxes.
Source of truth: `~/.local/share/chezmoi` on your main workstation.
Remote: `https://git.melonbread.xyz/rain/gnu-plus-dotfiles.git` (HTTPS for bootstrap, SSH from your main workstation for push — see Onboarding below).

## Branches

- `main` — current, bootstrap-enabled. All active work.
- `legacy-2025` — frozen snapshot of the pre-chezmoi-bootstrap config. Read-only.

## What's in here

```
.chezmoi.yaml.tmpl              os_family detection (debian | arch)
dot_zshrc.tmpl                  zsh config with os_family-conditional aliases
dot_tmux.conf                   tmux + tpm + gruvbox plugin stack
dot_gitconfig.tmpl              git + delta
dot_config/
  bat/                          bat config
  btop/                         btop theme + options
  ghostty/                      ghostty terminal + gruvbox themes
  kitty/                        kitty terminal + gruvbox themes
  nvim/                         LazyVim + custom plugins
  paru/                         (arch-only) paru config
  sway/                         sway + wofi + foot configs (desktops only)
  foot/                         foot terminal config
  wofi/                         wofi launcher configs + CSS
  waybar/                       waybar status bar
  mako/                         (arch-only) mako notification daemon

run_once_00-install-bootstrap-tools.sh.tmpl
run_once_05-install-hosts.sh.tmpl             merge LAN host entries into /etc/hosts
run_once_10-add-chaotic-aur.sh.tmpl            (arch-only)
run_once_20-install-user-packages.sh.tmpl
run_onchange_30-ensure-cargo.sh.tmpl
run_once_40-install-sway.sh.tmpl               (desktops only) sway + wofi + foot
```

## Onboarding a new box

**One command.** Copy/paste this on a fresh debian-stable or arch-base install:

```bash
sh -c "$(curl -fsSL https://raw.githubusercontent.com/...")" -- -b "$HOME/.local/bin" \
  && export PATH="$HOME/.local/bin:$PATH" \
  && chezmoi init --apply https://git.melonbread.xyz/rain/gnu-plus-dotfiles.git
```

Or as a heredoc that installs chezmoi then runs the bootstrap (more verbose, easier to read):

```bash
export PATH="$HOME/.local/bin:$PATH"
sh -c "$(curl -fsSL get.chezmoi.io)" -- -b "$HOME/.local/bin"
chezmoi init --apply https://git.melonbread.xyz/rain/gnu-plus-dotfiles.git
```

The bootstrap scripts run automatically as part of `chezmoi init --apply`. They will:

1. **run_once_00**: install `age`, `git`, `curl`, `ca-certificates` via the OS package manager
2. **run_once_05**: merge LAN host entries (`miche.local`, `kaiser.local`, etc.) into `/etc/hosts` so omp/curl can resolve them
3. **run_once_10** (arch only): add Chaotic-AUR repo + signing key, install `paru`
4. **run_once_20**: install zsh, tmux, neovim (binary tarball, arch-aware URL), oh-my-zsh + plugins (autosuggestions, syntax-highlighting, history-substring-search, fzf-tab), tpm, all modern CLI tools (`bat` via cargo or PM, `btop`, `eza`, `fzf`, `fd`, `ripgrep`, `zoxide`, `starship`, `lazygit`, `yt-dlp`, `jq`, etc.), set zsh as login shell (via `sudo chsh`), install Maple Mono NF font (GitHub release zip)
5. **run_onchange_30**: ensure rustup/cargo; install topgrade (`pacman` on arch via chaotic-aur, `cargo` on debian) and cargo-update

After bootstrap completes (~5-10 min on x86_64, longer on aarch64 with `cargo install bat`):

```bash
exec zsh
```

fastfetch will run on shell start, starship prompt active, all tools on PATH.

### Per-machine age key (required to decrypt secrets)

The repo contains encrypted secrets (`~/.omp/agent/zai.key`, `~/.omp/agent/.env`) that only your per-machine age key can decrypt. After bootstrap, generate the key on this box:

```bash
age-keygen -o ~/.config/chezmoi/key.txt
# Paste the printed public key into ~/.local/share/chezmoi/.chezmoi.yaml.tmpl
# under the recipients list, then:
cd ~/.local/share/chezmoi
git pull
# (You'll be prompted to add --force if you have local changes)
chezmoi apply
```

If you skip this step, the omp config files will still land (they're not encrypted), but `zai.key` and `.env` will be missing and omp won't be able to authenticate against providers.

## Sway / Wayland desktop stack

Sway + wofi + foot + waybar + swaybg/lock/idle + grim/slurp + wl-clipboard is opt-in at bootstrap time. The user decides per-box.

**Bootstrap prompt:** when you run `chezmoi init` for the first time on a new box, you'll be asked:

```
sway_setup (default false)? [y/N]
```

Answer `y` to install the packages + write the configs. Answer `N` (or just press enter) to skip. The answer is captured in `data.sway_setup` in the rendered `~/.config/chezmoi/chezmoi.yaml` and never re-asked.

**Subsequent flips** (per box, takes precedence over the bootstrap answer):
```bash
# Enable sway after the fact:
touch ~/.config/chezmoi/features/sway
chezmoi apply

# Disable sway (e.g. running a desktop headless as a server):
touch ~/.config/chezmoi/features/no-sway
rm -f ~/.config/chezmoi/features/sway
chezmoi apply
```

**Migration from hostname-allowlist:** the previous design auto-enabled sway on hostnames matching `miche`/`byte`/`kaiser`. That was removed. Existing desktops that already had sway installed kept the `~/.config/chezmoi/features/sway` marker, which now serves as the override-on signal — so they still have `sway_setup: true` without re-prompting.

**Migration of `chezmoi.yaml`:** if you ran the new template via SSH (no TTY), the prompt fails with "could not open a new TTY". Run it interactively (`chezmoi init`) from a real terminal, OR pass `--promptBool sway_setup=true|false` to set the value without prompting.

The `run_once_40-install-sway.sh` script:
- exits 0 with no side effects on non-sway boxes
- installs `sway wofi foot swaybg swaylock swayidle grim slurp waybar wl-clipboard` via `pacman` (arch) or `apt` (debian)
- adds `dunst` instead of `mako` on debian (mako isn't packaged for debian)
- creates the `~/.config/chezmoi/features/sway` marker so subsequent applies know it's enabled

The configs in `dot_config/{sway,foot,wofi,waybar,mako}/` are placed unconditionally — they're harmless on Pis (no tools to read them).

Sway is NOT auto-launched. It's installed as a tool you run manually from a TTY (`sway` from TTY1) for light desktops. The install and configs sit ready; launching is your call.

## Editing dotfiles

```bash
chezmoi edit ~/.zshrc          # opens in $EDITOR, auto-applies on save
chezmoi diff                   # see what's pending
chezmoi apply                  # apply pending changes
chezmoi cd                     # jump to the source repo
```

From inside `~/.local/share/chezmoi`, you can `git status`, `git diff`, `git push` like any normal repo.

## Common gotchas

- **Neovim too old on Debian**: `run_once_20` detects this and installs the official binary. If you see "Edit: command not found" inside LazyVim, neovim <0.9.
- **zsh plugins not loading**: check `~/.oh-my-zsh/custom/plugins/` exists. Bootstrap installs them.
- **paru 404 on arch**: Chaotic-AUR mirrors occasionally lag. Re-run `sudo pacman -Syu` then `chezmoi apply`.
- **fastfetch not running**: command not found, install via package manager. Debian needs `apt install fastfetch` (bookworm+).
- **`Maple Mono NF` font warning in nvim**: bootstrap should have installed it. Verify with `fc-list | grep -i maple`. If missing, see runbook skill `chezmoi-bootstrap-runbook` for manual install.

## Out of scope (intentionally not in repo)

- `~/.config/zsh/functions.zsh` — host-specific (reads `~/AI/llama.cpp/key.txt`). Recreate per host.
- KDE plasma configs (kwinrc, kdeglobals, etc.) — live state, varies wildly per host.
- Alacritty, foot, fish — not in use, drop if you want.
- mpv, topgrade, mako — out of scope unless re-added.