diff --git a/AGENTS.md b/AGENTS.md
index 67670b6..6002b46 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,26 +1,193 @@
-# Agent Guidelines for m3ta-nixpkgs
+# m3ta-nixpkgs Knowledge Base
 
-## 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)
+**Generated:** 2025-12-29
+**Commit:** 9092e6d
+**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
+```
+
+## 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` |
+
+## 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
-- **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
+**Formatter**: `nix fmt` before commit (nixpkgs-fmt)
+
+**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** (code2prompt):
+```nix
+rustPlatform.buildRustPackage rec {
+  cargoLock.lockFile = src + "/Cargo.lock";
+}
+```
+
+**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
+
+| 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` where type is: feat, fix, docs, style, refactor, chore
+
+```
+type: brief description
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
+
+## Gotchas
+
+- **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`
diff --git a/modules/home-manager/AGENTS.md b/modules/home-manager/AGENTS.md
new file mode 100644
index 0000000..c08b63c
--- /dev/null
+++ b/modules/home-manager/AGENTS.md
@@ -0,0 +1,74 @@
+# Home Manager Modules
+
+User-level configuration modules organized by functional category.
+
+## Structure
+
+```
+home-manager/
+├── default.nix      # Aggregator: imports all categories + ports.nix
+├── ports.nix        # Port management (HM-specific: generateEnvVars)
+├── cli/             # Terminal/CLI tools
+│   ├── default.nix  # Category aggregator
+│   └── zellij-ps.nix
+└── coding/          # Development tools
+    ├── default.nix  # Category aggregator
+    └── editors.nix  # Neovim + Zed configs
+```
+
+## Where to Look
+
+| Task | Location |
+|------|----------|
+| Add CLI module | `cli/<name>.nix`, import in `cli/default.nix` |
+| Add coding module | `coding/<name>.nix`, import in `coding/default.nix` |
+| Add new category | Create `<category>/default.nix`, import in root `default.nix` |
+| Module with host ports | Import `../../lib/ports.nix`, use `mkPortHelpers` |
+
+## Option Namespaces
+
+- `cli.*` - CLI tools (e.g., `cli.zellij-ps.enable`)
+- `coding.editors.*` - Editor configs (e.g., `coding.editors.neovim.enable`)
+- `m3ta.ports.*` - Port management (shared with NixOS)
+
+## Patterns
+
+**Category aggregator** (`cli/default.nix`):
+```nix
+{
+  imports = [
+    ./zellij-ps.nix
+    # Add new modules here
+  ];
+}
+```
+
+**Simple module** (zellij-ps):
+```nix
+options.cli.zellij-ps = {
+  enable = mkEnableOption "...";
+  projectFolders = mkOption { type = types.listOf types.path; ... };
+};
+config = mkIf cfg.enable {
+  home.packages = [ pkgs.zellij-ps ];
+  home.sessionVariables.PROJECT_FOLDERS = ...;
+};
+```
+
+**Multi-config module** (editors.nix):
+```nix
+config = mkMerge [
+  (mkIf cfg.neovim.enable { programs.neovim = {...}; })
+  (mkIf cfg.zed.enable { programs.zed-editor = {...}; })
+  (mkIf (cfg.neovim.enable || cfg.zed.enable) { home.packages = [...]; })
+];
+```
+
+## HM vs NixOS Differences
+
+| Feature | Home Manager | NixOS |
+|---------|--------------|-------|
+| `currentHost` default | `null` (must set) | `config.networking.hostName` |
+| `generateEnvVars` | Available | Not available |
+| Output file | `~/.config/m3ta/ports.json` | `/etc/m3ta/ports.json` |
+| Package access | `pkgs.*` via overlay | `pkgs.*` via overlay |