dotfiles/AGENTS.md

AGENTS.md — Agentic Coding Guide for Dotfiles

Setup, Lint, and Test

• Main entrypoint: ./setup.sh (runs all modules/*.sh in order)
• To re-run a single module: bash modules/XX-name.sh
• All scripts must be idempotent and safe to re-run
• No traditional build/lint/test; test by running setup and checking symlinks/configs

Code Style & Conventions

• Bash scripts only; use paru for package management (never pacman)
• Add new packages to the relevant modules/XX-*.sh script
• Place new dotfiles in repo root or .config/ as appropriate
• Symlinking logic is in modules/02-symlinks.sh
• Scripts must be modular: one concern per module, no duplicated logic
• Use $HOME and relative paths, never hardcode absolute paths
• Prefer arrays for package lists, and always quote variables
• Use set -e for error handling in scripts
• Follow naming: XX-feature.sh for modules, lowercase, hyphen-separated
• App configs (Hyprland, Waybar, etc.) go in .config/ and use includes/fragments if possible
• All scripts and configs should be readable, commented, and extensible

Device Profiles

• Support multiple device types (e.g., laptop, desktop) via an environment variable or setup prompt (DOTFILES_DEVICE=laptop|desktop)
• Use device-specific config fragments (e.g., monitors-laptop.conf, monitors-desktop.conf) and symlink/include them conditionally
• Waybar, Hyprland, and input configs should only enable battery, backlight, wifi, and touchpad modules for laptops
• Setup scripts and symlinking logic must detect device type and use the correct configs

Copilot/AI Rules

• See .github/copilot-instructions.md for full conventions
• Never use other package managers or hardcoded paths
• All changes must be modular, idempotent, and version-controlled

For more, see README.md and .github/copilot-instructions.md.

Commit Workflow

• After every change, stage and commit your work with a clear, descriptive commit message explaining the purpose of the change (not just the file or function name)
• Example: git add <changed-files> && git commit -m "fix: correct Waybar config for desktop profile"
• Always commit after each logical change, not just at the end of a session
• The commit message should focus on the "why" and "what" (e.g., "fix: remove battery module for desktop profile")
• Do not use generic messages like "Update" or "Fix" without context