AGENTS.md — Agentic Coding Guide for Dotfiles

🚨 ABSOLUTE AGENT SAFETY RULES — DO NOT IGNORE 🚨

Agents MUST NEVER run any scripts in this repo automatically.
Agents MUST NEVER modify, symlink, or touch files outside of the repo root or its subdirectories.
NO file operations or script executions unless the user gives direct, explicit permission for each action.
All actions must be idempotent, explicit, and user-approved.
Violating these rules risks breaking the user’s system and is strictly forbidden.

Build/Lint/Test

Main entrypoint: ./setup.sh (runs all modules/*.sh in order)
To run a single module: bash modules/XX-name.sh
No traditional build/lint/test; test by running setup and verifying symlinks/configs
NEVER run the scripts on your own, ALWAYS ask for permission

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

Support device types via DOTFILES_DEVICE=laptop|desktop; use device-specific config fragments and conditional symlinking

After every change, commit with a clear, descriptive message explaining the purpose (not just the file or function name)
Example: git add <changed-files> && git commit -m "fix: correct Waybar config for desktop profile"
Do not use generic messages like "Update" or "Fix" without context