# Agent Guidelines for m3ta-nixpkgs

## Build/Lint/Test Commands
- `nix flake check` - Validate flake and run checks
- `nix fmt` - Format all Nix files (uses nixpkgs-fmt)
- `nix build .#<package>` - Build a specific package
- `nix flake show` - List all available outputs
- `statix check .` - Lint Nix files (run in `nix develop` shell)
- `deadnix .` - Find dead/unused Nix code (run in `nix develop` shell)

## Code Style
- **Formatter**: Always run `nix fmt` before committing
- **Naming**: Package names use lowercase-hyphen (`my-package`), variables use camelCase
- **Imports**: Multi-line with trailing commas: `{ lib, stdenv, fetchFromGitHub, }:`
- **Modules**: Use `with lib; let cfg = config.namespace.module; in { ... }` pattern
- **Options**: Use `mkEnableOption` for enable flags, namespace under `m3ta.*`
- **Meta**: Always include description, homepage, license, platforms, mainProgram
- **Comments**: Explain "why" not "what"; document non-obvious logic

## File Organization
- One package per directory under `pkgs/`, entry point is `default.nix`
- Register packages in `pkgs/default.nix` using `callPackage`
- Modules go in `modules/nixos/` or `modules/home-manager/` by category

## Commit Format
`type: brief description` where type is: feat, fix, docs, style, refactor, chore