docs: add hierarchical AGENTS.md knowledge base
- Update root AGENTS.md with regenerative content (144 lines, telegraphic) - Add pkgs/AGENTS.md for package registry conventions (33 lines) - Add docs/AGENTS.md for documentation structure (34 lines) - All files follow telegraphic style, no redundancy with parent - Preserves existing modules/home-manager/AGENTS.md Hierarchy: ./AGENTS.md (root) ├── pkgs/AGENTS.md ├── docs/AGENTS.md └── modules/home-manager/AGENTS.md (existing)
This commit is contained in:
m3tm3re
141
AGENTS.md
141
AGENTS.md
@@ -1,14 +1,14 @@
|
||||
# m3ta-nixpkgs Knowledge Base
|
||||
|
||||
**Generated:** 2025-12-29
|
||||
**Commit:** 9092e6d
|
||||
**Generated:** 2025-12-30
|
||||
**Commit:** c5e1610
|
||||
**Branch:** master
|
||||
|
||||
## Overview
|
||||
## OVERVIEW
|
||||
|
||||
Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev shells. Flakes-only (no channels).
|
||||
|
||||
## Structure
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
.
|
||||
@@ -24,7 +24,7 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
|
||||
└── examples/ # Usage examples
|
||||
```
|
||||
|
||||
## Where to Look
|
||||
## WHERE TO LOOK
|
||||
|
||||
| Task | Location | Notes |
|
||||
|------|----------|-------|
|
||||
@@ -35,23 +35,7 @@ Personal Nix flake: custom packages, overlays, NixOS/Home Manager modules, dev s
|
||||
| Add dev shell | `shells/<name>.nix` | Register in `shells/default.nix` |
|
||||
| Use port management | `config.m3ta.ports.get "service"` | Host-specific via `hostOverrides` |
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
nix flake check # Validate flake
|
||||
nix fmt # Format (nixpkgs-fmt)
|
||||
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
|
||||
```
|
||||
|
||||
## Code Style
|
||||
## CONVENTIONS
|
||||
|
||||
**Formatter**: `nix fmt` before commit (nixpkgs-fmt)
|
||||
|
||||
@@ -93,80 +77,47 @@ meta = with lib; {
|
||||
};
|
||||
```
|
||||
|
||||
## Package Patterns
|
||||
## PACKAGE PATTERNS
|
||||
|
||||
**Rust** (code2prompt):
|
||||
```nix
|
||||
rustPlatform.buildRustPackage rec {
|
||||
cargoLock.lockFile = src + "/Cargo.lock";
|
||||
}
|
||||
**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 (nixpkgs-fmt)
|
||||
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
|
||||
```
|
||||
|
||||
**Shell scripts** (launch-webapp):
|
||||
```nix
|
||||
writeShellScriptBin "name" ''script''
|
||||
# Or mkDerivation with custom installPhase
|
||||
```
|
||||
|
||||
**AppImage** (msty-studio):
|
||||
```nix
|
||||
appimageTools.wrapType2 { ... }
|
||||
```
|
||||
|
||||
**Custom fetcher** (zellij-ps):
|
||||
```nix
|
||||
fetchFromGitea {
|
||||
domain = "code.m3ta.dev";
|
||||
owner = "m3tam3re";
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Module Patterns
|
||||
|
||||
**Simple enable** (zellij-ps.nix):
|
||||
```nix
|
||||
options.cli.zellij-ps = {
|
||||
enable = mkEnableOption "...";
|
||||
someOption = mkOption { type = types.str; default = "..."; };
|
||||
};
|
||||
config = mkIf cfg.enable { home.packages = [...]; };
|
||||
```
|
||||
|
||||
**Multiple conditionals** (editors.nix):
|
||||
```nix
|
||||
config = mkMerge [
|
||||
(mkIf cfg.neovim.enable { ... })
|
||||
(mkIf cfg.zed.enable { ... })
|
||||
(mkIf (cfg.neovim.enable || cfg.zed.enable) { ... })
|
||||
];
|
||||
```
|
||||
|
||||
**Shared library** (ports modules):
|
||||
```nix
|
||||
portsLib = import ../../lib/ports.nix { inherit lib; };
|
||||
portHelpers = portsLib.mkPortHelpers { ports = cfg.definitions; ... };
|
||||
```
|
||||
|
||||
## Port Management
|
||||
|
||||
Central port management with host-specific overrides:
|
||||
|
||||
```nix
|
||||
m3ta.ports = {
|
||||
enable = true;
|
||||
definitions = { nginx = 80; grafana = 3000; };
|
||||
hostOverrides.laptop = { nginx = 8080; };
|
||||
currentHost = config.networking.hostName; # NixOS auto
|
||||
};
|
||||
|
||||
# Usage
|
||||
services.nginx.port = config.m3ta.ports.get "nginx";
|
||||
```
|
||||
|
||||
**Generated files**: `/etc/m3ta/ports.json` (NixOS), `~/.config/m3ta/ports.json` (HM)
|
||||
|
||||
## Anti-Patterns
|
||||
## ANTI-PATTERNS
|
||||
|
||||
| Don't | Do Instead |
|
||||
|-------|------------|
|
||||
@@ -176,7 +127,7 @@ services.nginx.port = config.m3ta.ports.get "nginx";
|
||||
| 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
|
||||
## COMMIT FORMAT
|
||||
|
||||
```
|
||||
type: brief description
|
||||
@@ -184,7 +135,7 @@ type: brief description
|
||||
|
||||
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
|
||||
|
||||
## Gotchas
|
||||
## NOTES
|
||||
|
||||
- **Hash fetching**: Use `lib.fakeHash` initially, build to get real hash
|
||||
- **HM modules**: Category subdirs (`cli/`, `coding/`) have own `default.nix` aggregators
|
||||
|
||||
Reference in New Issue
Block a user