nixpkgs/AGENTS.md

# m3ta-nixpkgs Knowledge Base

**Generated:** 2026-01-13
**Commit:** 366af12
**Branch:** master

## OVERVIEW

Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).

## STRUCTURE

```
.
├── flake.nix              # Entry: packages, overlays, modules, shells, lib
├── pkgs/                  # Custom packages (one dir each, callPackage registry)
├── modules/
│   ├── nixos/             # System modules (ports.nix)
│   └── home-manager/      # User modules by category (cli/, coding/, ports.nix)
├── lib/                   # Shared utilities (ports.nix)
├── shells/                # Dev environments (default, python, devops)
├── overlays/mods/         # Package modifications (n8n version bump)
├── templates/             # Boilerplate for new packages/modules
├── examples/              # Usage examples
└── .gitea/workflows/     # CI/CD workflows (nix-update automation)
```

## WHERE TO LOOK

| Task                 | Location                           | Notes                                 |
| -------------------- | ---------------------------------- | ------------------------------------- |
| Add package          | `pkgs/<name>/default.nix`          | Register in `pkgs/default.nix`        |
| Add NixOS module     | `modules/nixos/<name>.nix`         | Import in `modules/nixos/default.nix` |
| Add HM module        | `modules/home-manager/<category>/` | Category: cli, coding, or root        |
| Override nixpkgs pkg | `overlays/mods/<name>.nix`         | Import in `overlays/mods/default.nix` |
| Add dev shell        | `shells/<name>.nix`                | Register in `shells/default.nix`      |
| Use port management  | `config.m3ta.ports.get "service"`  | Host-specific via `hostOverrides`     |
| CI/CD workflows      | `.gitea/workflows/<name>.yml`      | Automated package updates (nix-update) |

## CONVENTIONS

**Formatter**: `nix fmt` before commit (alejandra)

**Naming**:

- Packages: `lowercase-hyphen` (e.g., `hyprpaper-random`)
- Variables: `camelCase` (e.g., `portHelpers`)
- Module options: `m3ta.*` namespace

**Imports**: Multi-line, trailing commas:

```nix
{
  lib,
  stdenv,
  fetchFromGitHub,
}:
```

**Modules**: Standard pattern:

```nix
{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
  };
  config = mkIf cfg.enable { ... };
}
```

**Meta**: Always include all fields:

```nix
meta = with lib; {
  description = "...";
  homepage = "...";
  license = licenses.mit;
  platforms = platforms.linux;
  mainProgram = "...";
};
```

## PACKAGE PATTERNS

**Rust**: `rustPlatform.buildRustPackage rec { cargoLock.lockFile = src + "/Cargo.lock"; }`

**Shell**: `writeShellScriptBin "name" ''script''` or `mkDerivation` with custom `installPhase`

**AppImage**: `appimageTools.wrapType2 { ... }`

**Custom fetcher**: `fetchFromGitea { domain = "code.m3ta.dev"; owner = "m3tam3re"; ... }`

## MODULE PATTERNS

**Simple**: `options.cli.name = { enable = mkEnableOption "..."; }; config = mkIf cfg.enable { ... };`

**Multiple**: `config = mkMerge [ (mkIf cfg.x.enable { ... }) (mkIf cfg.y.enable { ... }) ];`

**Shared lib**: `portsLib = import ../../lib/ports.nix { inherit lib; }; portHelpers = portsLib.mkPortHelpers { ... };`

## PORT MANAGEMENT

Central port management: `config.m3ta.ports.get "service"` with host-specific via `hostOverrides`

Generated: `/etc/m3ta/ports.json` (NixOS), `~/.config/m3ta/ports.json` (HM)

## COMMANDS

```bash
nix flake check              # Validate flake
nix fmt                      # Format (alejandra)
nix build .#<pkg>            # Build package
nix flake show               # List outputs
nix develop                  # Enter dev shell
nix develop .#python         # Python shell
nix develop .#devops         # DevOps shell

# In dev shell only:
statix check .               # Lint
deadnix .                    # Find dead code
```

## ANTI-PATTERNS

| Don't                     | Do Instead                                                          |
| ------------------------- | ------------------------------------------------------------------- |
| `lib.fakeHash` in commits | Get real hash: `nix build`, copy from error                         |
| Flat module files         | Organize by category (`cli/`, `coding/`)                            |
| Hardcode ports            | Use `m3ta.ports` module                                             |
| Skip meta fields          | Include all: description, homepage, license, platforms, mainProgram |
| `with pkgs;` in modules   | Explicit `pkgs.package` or `with pkgs; [ ... ]` in lists only       |

## COMMIT FORMAT

```
type: brief description
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`

## NOTES

- **Hash fetching**: Use `lib.fakeHash` initially, build to get real hash
- **HM modules**: Category subdirs (`cli/`, `coding/`) have own `default.nix` aggregators
- **Ports module**: Different for NixOS vs HM (HM adds `generateEnvVars` option)
- **Overlays**: `modifications` overlay uses `{prev}:` pattern, not `{final, prev}:`
- **Dev shell tools**: `statix`, `deadnix` only available inside `nix develop`
- **Automated package updates**: Packages are automatically updated weekly via Gitea Actions using `nix-update`. Review PRs from the automation before merging. For urgent updates, manually run the workflow or update manually.

## Issue Tracking

This project uses **bd (beads)** for issue tracking.
Run `bd prime` for workflow context, or install hooks (`bd hooks install`) for auto-injection.

**Quick reference:**

- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd sync` - Sync with git (run at session end)

For full workflow details: `bd prime`