dotfiles/AGENTS.md

# 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

## Code Style & Conventions
- 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

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

## Copilot/AI Rules
- See `.github/copilot-instructions.md` for full conventions
- All changes must be modular, idempotent, and version-controlled

## Commit Workflow
- 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