AGENTS.md

This file guides AI assistants when working in this dotfiles repository.

Repository overview

• GNU Stow manages symlinks from this repo into the home directory.
• Primary environment is Ubuntu on WSL. Plain Linux should follow the same structure; Windows-specific setup is manual and secondary.
• Each stowed app should keep the shape it needs under $HOME. Most app configs live in <app>/.config/<app>/, which becomes ~/.config/<app>/ after stowing.
• .stowrc sets --target=~/, so run stow from the repo root.

Setup expectations

• Ubuntu base packages are listed in ubuntu_packages and can be installed with apt, for example:

  sudo apt update
  xargs -a ubuntu_packages sudo apt install -y
  

• Keep package lists as plain package names, one per line, unless the consuming command changes.

Key technologies

• Neovim: AstroNvim + Lazy.nvim
  • Entry points: nvim/.config/nvim/init.lua -> lua/lazy_setup.lua -> lua/polish.lua
  • Formatting: Stylua, configured by nvim/.config/nvim/.stylua.toml
  • Linting: Selene, configured by nvim/.config/nvim/selene.toml
  • Do not commit nvim/.config/nvim/lazy-lock.json; it is intentionally ignored.
• Zsh: Zim framework
  • Main file: zsh/.zshrc
  • Plugin definition: zsh/.zimrc
  • Optional untracked overlays: ~/.zshpersonal, ~/.zshwork
• Mise: mise/.config/mise/config.toml
• WezTerm: wezterm/.config/wezterm/wezterm.lua
• Other stowable configs include Atuin, Bat, Btop, Gdu, IdeaVim, Lazygit, Poetry, VS Code-family editors, and Zellij.

Common commands

• Stow one or more configs:

  stow zsh nvim wezterm mise
  

• Remove or restow a config:

  stow -D nvim
  stow -R nvim
  

Verification after edits

• Zsh: source ~/.zshrc or start a new shell.
• Neovim: open nvim, then run :checkhealth.
• WezTerm: restart or reload the config.
• Stow structure: run stow -n -v <app> for a dry run when changing package layout.

Change guidelines

• Keep edits minimal and scoped to the requested config or documentation.
• Preserve Unix line endings.
• Follow the existing <app>/.config/<app>/ layout unless the target program expects a different home-relative path.
• Prefer explicit, readable configuration over clever indirection.
• Do not reformat unrelated files.
• Do not commit generated lockfiles from plugin managers.

Windows notes

• Windows paths and config locations can differ from Linux/WSL.
• Manual symlinks may be needed for native Windows tools.
• Keep Windows-only instructions in README addenda unless the task is specifically about Windows.