1 files changed, 72 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8989112
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,72 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This is a Guix Home Environment configuration repository. Declarative system and home configurations are managed through Scheme (`.scm`) files.
+
+**Directory layout:**
+
+```
+├── home.scm           # Home environment configuration (user services)
+├── system.scm         # System-wide configuration
+├── secrets.scm        # Sensitive configuration (passwords, tokens)
+├── config/            # Extracted configuration modules
+│   ├── packages.scm   # Package definitions
+│   ├── sway.scm       # Sway window manager config
+│   ├── emacs.scm      # Emacs configuration
+│   ├── foot.scm       # Foot terminal config
+│   └── git.scm        # Git configuration
+├── wofi/              # Wofi application launcher assets
+├── config-generation/ # Helper modules for config generation
+└── reconfigure*       # Convenience scripts for deployment
+```
+
+**Module pattern:** Extract configurations into `config/*.scm` using `(define-library (config <name>))` with exported variables renamed in `home.scm` (e.g., `(rename (config git) (git-config rz/git-config))`).
+
+## Build, Test, and Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `guix home reconfigure home.scm` | Apply home environment changes |
+| `guix system reconfigure system.scm` | Apply system-wide changes |
+| `guix home reconfigure home.scm --dry-run` | Validate configuration without applying |
+| `./reconfigure-home` | Convenience script for home reconfiguration |
+| `./reconfigure-system` | Convenience script for system reconfiguration |
+
+## Coding Style & Naming Conventions
+
+- **Indentation:** 8 spaces for Scheme files (Guix standard)
+- **File extensions:** `.scm` for all Scheme modules
+- **Module naming:** `(config <module-name>)` for extracted configurations
+- **Variable naming:** Use `rz/` prefix for renamed exports (e.g., `rz/git-config`, `rz/sway-config`)
+- **Comments:** Begin files with `;;;` for major sections, use `;;` for inline comments
+
+**INI configuration pattern:**
+```scheme
+(define <name>-config
+  (parameterize
+      ((current-output-port (open-output-string)))
+    (scm->ini <data>)
+    (get-output-string (current-output-port))))
+```
+
+## Testing Guidelines
+
+- Use `--dry-run` flag to validate configurations before deployment
+- Verify syntax with: `guile -c "(load \"config/<module>.scm\")"`
+- Test configuration generation with `guix home config` to preview outputs
+
+## Commit & Pull Request Guidelines
+
+- **Commit messages:** Use imperative present tense (e.g., "Add git config module", "Update sway colors")
+- **Scope indication:** Prefix with affected component (e.g., "[home.scm]", "[config/git.scm]")
+- **Pull requests:** Include description of changes and any related configuration dependencies
+- Extract large configuration blocks into dedicated modules before adding to main files
+
+## Agent-Specific Instructions
+
+- **Ignore backup files:** All files ending with `~` are backup/temporary files and should be ignored during analysis and modification.
+
+- Check for existing `config/*.scm` modules before creating new ones
+- Use `home.scm` imports to understand the module dependency graph
+- Run validation commands before marking configuration changes complete