AGENTS.md: add hierarchical documentation for hosts, home, features, services

hosts/AGENTS.md

@@ -0,0 +1,64 @@
+# hosts/ - NixOS Host Configurations
+
+Host-specific NixOS system configurations. Each `m3-*` directory is a complete host.
+
+## Structure
+
+```
+hosts/
+├── common/           # Shared by ALL hosts
+│   ├── extraServices/  # Toggle-able services (ollama, podman, flatpak)
+│   ├── users/          # User definitions
+│   ├── ports.nix       # Central port registry
+│   └── default.nix     # Overlays, nix settings, home-manager integration
+└── m3-*/             # Per-host configurations
+    ├── default.nix       # Entry point (imports common + enables extraServices)
+    ├── configuration.nix # Core system (boot, networking, stateVersion)
+    ├── hardware-configuration.nix
+    ├── programs.nix      # Host-specific packages
+    ├── secrets.nix       # Agenix secret declarations
+    └── services/         # Service configs
+        └── containers/   # OCI container definitions (m3-atlas only has many)
+```
+
+## Adding a New Host
+
+1. Create `hosts/m3-<name>/` with required files
+2. Add to `flake.nix` nixosConfigurations
+3. Create matching `home/m3tam3re/m3-<name>.nix`
+
+## Host Quick Reference
+
+| Host | extraServices | Has disko | Key services/ files |
+|------|---------------|-----------|---------------------|
+| m3-atlas | podman | Yes | traefik, postgres, gitea, containers/* |
+| m3-helios | - | Yes | adguard, traefik, containers/homarr |
+| m3-ares | podman | No | wireguard, tailscale, sound |
+| m3-kratos | podman, ollama | No | wireguard, tailscale, sound |
+| m3-aether | - | Yes | cloud-init (minimal) |
+
+## extraServices Pattern
+
+Enable in host's `default.nix`:
+```nix
+extraServices = {
+  podman.enable = true;
+  ollama.enable = true;
+  flatpak.enable = false;
+  virtualisation.enable = false;
+};
+```
+
+## Port Allocation
+
+ALWAYS check `common/ports.nix` before adding new services. Register new ports there.
+
+## Secrets Declaration
+
+Each host's `secrets.nix` declares only secrets it needs:
+```nix
+age.secrets.service-name = {
+  file = ../../secrets/service-name.age;
+  owner = "optional-user";
+};
+```