# 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
│   └── ssh.scm        # SSH client 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`.

**Configuration generation patterns:**

- **`scm->ini` helper (foot.scm, git.scm):** Use the `scm->ini` function from the `ini` library to generate configuration files from association lists. Git config (INI format) and Foot terminal config (INI format) use this pattern. These modules export a single `<name>-config` string variable.

- **Guix service records (ssh.scm, sway.scm):** Use native Guix service records like `openssh-host` and `sway-configuration`. The SSH module exports both host records for the `home-openssh-service-type` service and a config string for XDG deployment. SSH config uses native SSH format (key-value pairs under Host blocks), not INI format.

- **String-based (emacs.scm):** Direct string content exported as `<name>-config` for XDG config files service deployment.

## 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 build home.scm` | Validate and build configuration |
| `./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`, `rz/ssh-config`)
- **Comments:** Begin files with `;;;` for major sections, use `;;` for inline comments

**Module export patterns:**

- INI-based modules (foot.scm, git.scm) export `<name>-config` as string content
- Service-based modules (ssh.scm, sway.scm) export both service records and config file content where applicable
- String-based modules (emacs.scm) export `<name>-config` as string content

## 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
- **Configuration format awareness:** Distinguish between INI-based configs (git, foot) and native format configs (ssh, sway, emacs) when generating or modifying configuration content