Tooling

### 🔄 Project Awareness & Context

- **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
- **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`.

### 🧱 Code Structure & Modularity

- **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files.
- **Organize code into clearly separated modules**, grouped by feature or responsibility.
- **Use clear, consistent imports** (prefer relative imports within packages).
- **Modularity**: Break down configurations into reusable modules
- **DRY (Don't Repeat Yourself)**: Extract common patterns into functions or modules
- **Naming Conventions**: Use descriptive, consistent names for modules and variables

### Nix Best Practices

1. **Package References**:

   - Use `outPath` when creating symlinks to package locations
   - Prefer `mkOutOfStoreSymlink` for package paths

2. **VS Code Extensions**:
   - Path: `${config.home.path}/share/vscode/extensions`
   - Configuration:
     - Enable in `programs.vscode`
     - Configure extensions using the `extensions` attribute

### Module Structure

```nix
{
  # Function arguments
  config,
  lib,
  pkgs,
  ...
}:

with lib;


{
  # Module implementation
  options = {
    # Define your module options here
  };


  config = mkIf config.yourmodule.enable {
    # Configuration implementation
  };
}
```

### 📚 Documentation & Explainability

- **Update `README.md`** when new features are added, dependencies change, or setup steps are modified.
- **Comment non-obvious code** and ensure everything is understandable to a mid-level developer.
- When writing complex logic, **add an inline `# Reason:` comment** explaining the why, not just the what.

### 🧠 AI Behavior Rules

- **Never assume missing context. Ask questions if uncertain.**
- **Never hallucinate libraries or functions** – only use known, verified packages.
- **Always confirm file paths and module names** exist before referencing them in code or tests.
- **Never delete or overwrite existing code** unless explicitly instructed to.

### 🧪 Testing & Reliability

This project uses `just` for command running:

- To test that a build will compile without errors, run:
  ```bash
  just build
  ```

**Important**: Only run this command on the local machine. Do not execute it using colmena on remote machines.

### 📎 Style & Conventions

- **Use Nix** as the primary language.
- **Follow NixOS** style and best practices.

## Tooling

- **MCP Servers**:
  - Always use `context7` to ensure proper syntax when you write code

## Debugging Common Issues

### Missing Nix Files

If you encounter an error indicating that a Nix file does not exist, this is typically because:

- The file is newly created and not yet tracked by Git
- The file exists in your working directory but hasn't been staged

**Solution**:

```bash
git add /path/to/new/file.nix
```

This ensures Nix can properly resolve file paths during evaluation. This is particularly important when using `import` statements or file-based configurations.

### Git Repository Not Found

If you see an error similar to:

```
cannot find Git revision of repository 'ssh://git@github.com/fred-drake/nix-secrets.git'
```

**Solution**:
Run the following command to fetch the latest version of the secrets repository:

```bash
just update-secrets
```

This will ensure all required repositories are properly fetched and available for Nix evaluation.

## Contributing

When making changes:

1. Test configurations locally when possible
2. Document new modules and functions
3. Keep configurations modular and reusable
4. Follow existing patterns for consistency