# dotfiles repo agent guide

This repo is a collection of personal config files deployed via GNU Stow.

## How it works

- Each subdirectory is a **stow package**: `bash`, `zsh`, `git`, `starship`.
- Directory structure mirrors `$HOME` (e.g. `git/.gitconfig` → `~/.gitconfig`).

## Commands

```bash
# Deploy all packages (auto-installs stow via apt if missing)
./setup.sh

# Selective install
./setup.sh --only=git,zsh

# Preview without changes
./setup.sh --dry-run

# Remove symlinks
./uninstall.sh
./uninstall.sh --only=git      # selective removal
```

All scripts accept `--verbose`, `--quiet`, `--dry-run`.

## Adding a new package

```bash
mkdir <name>
cp ~/.<configfile> <name>/
./setup.sh --only=<name>
```

## Toolchain auto-installed by setup.sh

`setup.sh` installs these tools to `~/.local/bin` if not already present — do not add manual install steps for them: **zinit** (zsh plugin manager), **zoxide** (smart cd), **fzf**, **bat**, **eza**, **delta**, **ripgrep**.

## Theming convention

All tools are themed with **Gruvbox Dark Hard**. When adding config for a new tool, apply Gruvbox colors to keep the environment cohesive.

## Important constraints

- Default shell is **zsh** (`bash/.bashrc` does NOT exec zsh — set your default shell with `chsh`). Uses **zinit** as plugin manager (turbo mode for async loading).
- `.bashrc` sources `~/.bash_aliases`; `.zshrc` sources `~/.zsh_aliases`.
- **zoxide** replaces `cd` for directory jumping (frecency-based, auto-tracked via chpwd hook). `j` alias for `zoxide cd`.
- **Sensitive files are gitignored**: `.netrc`, SSH keys (`id_rsa*`, `known_hosts`), gradle caches.
- No build, test, lint, or typecheck steps — this is pure config.
- Backups of pre-existing real files are created at `~/.dotfiles-backup-YYYYMMDD-HHMMSS` before stowing.