dotfiles/.github/copilot-instructions.md

Copilot Instructions for This Dotfiles Project

Project Overview

• This is a modular dotfiles and desktop setup for Arch Linux, focused on Wayland/Hyprland workflows.
• All package management is done with paru (AUR helper). Do not use pacman or other helpers.
• Dotfiles and app configs are version-controlled in the repo root and .config/ directory, then symlinked to $HOME and $HOME/.config.
• The setup is fully modular: each major component (packages, symlinks, shell, Neovim, Hyprland, sound, etc.) is handled by its own script in modules/.

Architecture & Workflow

• The main entrypoint is setup.sh, which finds and runs all numbered scripts in modules/ in sorted order.
• Each module script is responsible for a single concern (e.g., 01-packages.sh for package install, 05-hyprland.sh for Hyprland/Wayland packages, etc.).
• The symlinking logic (02-symlinks.sh) links all dotfiles (including .config/) from the repo to the home directory, so configs are always up to date and versioned.
• App configs (Hyprland, Waybar, etc.) are stored in .config/ and should be modular and extensible (e.g., Hyprland uses includes/ for config fragments).

Key Conventions

• Always add new packages to the appropriate module script (e.g., Hyprland-related to 05-hyprland.sh, sound to 06-sound.sh).
• To add new dotfiles, place them in the repo root (for files like .zshrc) or in .config/ for app configs.
• To add new setup logic, create a new numbered module in modules/ (e.g., 07-myfeature.sh).
• All scripts must be idempotent and safe to re-run.
• Use only paru for package installation.

Examples

• To add a new app config (e.g., for kitty):
  1. Place config files in .config/kitty/ in the repo.
  2. The symlink module will link them to $HOME/.config/kitty on setup.
• To add a new package:
  1. Edit the appropriate modules/XX-*.sh script and add the package to the array.
  2. Re-run setup.sh.
• To add a new setup step:
  1. Create modules/07-myfeature.sh and make it executable.
  2. It will be picked up automatically by setup.sh.

Integration Points

• Hyprland, Waybar, Rofi, Mako, Alacritty, wlogout, and sound are all integrated and configured via .config/.
• Neovim is set up with AstroNvim by default.
• Sound is managed with PipeWire, WirePlumber, and related tools.

Notable Patterns

• All configuration is declarative and modular. Avoid hardcoding paths; use $HOME and relative repo paths.
• Avoid duplicating logic between modules; each should have a single responsibility.

See Also

• README.md for user-facing setup and customization instructions.
• modules/ for all setup logic.
• .config/ for all app configs.