# 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