From d240aac403d2c00f78735553b58ed1e6febe55bc Mon Sep 17 00:00:00 2001 From: Christoph Urlacher Date: Sun, 13 Sep 2026 21:59:47 +0200 Subject: [PATCH] Add AGENTS.md --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..75e3e20 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# AGENTS.md + +## Common Commands + +```bash +# Enter the dev shell (provides helper utilities) +nix develop + +# Preferred shorthand (nh must be enabled in config) +nh os switch # rebuild and switch +nh os boot # new boot entry without switching + +# Direct nixos-rebuild (fallback) +sudo nixos-rebuild switch --flake .#nixinator +sudo nixos-rebuild switch --flake .#nixtop +sudo nixos-rebuild switch --flake .#servenix +sudo nixos-rebuild switch --flake .#thinknix +sudo darwin-rebuild switch --flake .#darwinix + +# Validate flake without building +nix flake check + +# Dev shell helpers (run inside `nix develop`) +list-system-packages # show installed system packages +list-user-packages # show installed user packages +store-optimise # nix store --optimise +store-verify # nix store --verify --repair +``` + +## MCP Tools + +The **nixos** MCP server is available and should be used for any Nix-related lookups instead of `nix search` or manual web searches. It queries live APIs (search.nixos.org, NixHub, FlakeHub) and is more current than training data. + +``` +# Common intents +nix {"action":"info","query":"","channel":"unstable"} # package info +nix {"action":"search","query":"","type":"options"} # NixOS options +nix {"action":"search","source":"home-manager","query":""} # HM options +nix {"action":"cache","query":""} # binary cache status +nix_versions {"package":"","version":""} # commit that shipped a version +``` + +## Architecture + +This is a multi-host NixOS/nix-darwin flake. Home-manager runs **as a NixOS module** — not standalone. A single `nixos-rebuild switch` rebuilds system and user config together. The HM config can access the system config via the `nixosConfig` special arg. + +### Hosts + +| Host | Type | Notes | +|------|------|-------| +| `nixinator` | Desktop (x86_64) | Primary machine; disko, lanzaboote, impermanence | +| `nixtop` | Laptop (x86_64) | Intel GPU, NetworkManager | +| `servenix` | Server (x86_64) | Headless; runs OCI container services | +| `thinknix` | Headless (x86_64) | Generic headless config | +| `darwinix` | macOS (aarch64) | Darwin-specific configuration | + +### Config Layering (resolved in this order) + +1. **Global defaults** — `system/default.nix` / `home/christoph/default.nix` +2. **Host overrides** — `system//default.nix` / `home/christoph//default.nix` +3. **Hardware** — `system//hardware-configuration.nix` (auto-generated, **do not hand-edit**) + +The builder (`lib/nixos.nix`: `mkNixosConfigWithHomeManagerModule`) wires these together. + +### Special Args + +Injected into **all system and HM modules**: +`inputs` `system` `hostname` `mylib` `username` `publicKeys` `headless` + +Use `headless` (boolean) to gate anything graphical. Use `mylib.` instead of reimplementing helpers. + +### Module System + +Two parallel hierarchies, identical pattern: + +| Scope | Path | Option prefix | +|-------|------|---------------| +| System | `system/systemmodules//` | `systemmodules..*` | +| Home-manager | `home/homemodules//` | `homemodules..*` | + +**System modules** — `system/systemmodules//` +- `options.nix` — declares `systemmodules..*` options +- `default.nix` — imports `./options.nix`, implements `lib.mkIf .enable { ... }` + +**Home-manager modules** — `home/homemodules//` +- `options.nix` — declares `homemodules..*` options +- `default.nix` — same pattern under `homemodules.*` + +When adding a new module, copy from `0_template/` in either hierarchy. Modules under `1_deprecated/` are kept for reference only — not imported anywhere. + +HM modules are placed in `home-manager.sharedModules` (not `users..imports`) — this enables proper nixd completions. + +### Custom Library (`lib/`) + +Always available as `mylib`. Key files: +- `nixos.nix` — host config builders, `mkNixosConfigWithHomeManagerModule`, `mkDarwinConfigWithHomeManagerModule` +- `modules.nix` — `mkBoolOption`, `mkElse`, `attrName`, `attrValue`, `contains` +- `networking.nix` — `mkSystemdNetwork`, `mkStaticSystemdNetwork` +- `generators.nix` — `toLuaObject`, `toLuaKeymap` (used by Neovim module) +- `containers.nix` — OCI container helpers for services +- `color.nix` — theming + +Always use `mylib.` (available as a special arg) rather than reimplementing these utilities. + +### Services + +Server services are OCI containers (podman/docker) defined in `system/services/`. Each file defines one or more containers. These are only enabled on `servenix`. Use the template at `system/services/0_TEMPLATE.nix`. + +### Secrets + +Managed via **sops-nix**. Age keys stored in `flake.nix` under `publicKeys.christoph`. Encrypted `.yaml`/`.json` files live alongside the module that uses them, referenced as `sops.secrets.`. + +### Overlays and Custom Derivations + +- `overlays/default.nix` — package overrides (e.g., patched JetBrains CLion version) +- `derivations/default.nix` — custom packages: `monolisa`, `msty`, `unityhub`, `tidal-dl-ng`, `tiddl` +- `derivations/1_deprecated/` — kept for reference, not imported + +### Sub-projects + +`config/flake.nix` is a separate, reusable development-project template — **not part of the main NixOS flake**. It uses `flake-utils` for multi-system shells. + +## Constraints + +- No CI, no tests, no linting — this is a configuration repo +- `nix flake check` is the only validation available +- `documentation.enable = false` by default (slow); toggle it if you need man pages +- Hardware config files are auto-generated — never edit them by hand