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";
+};
+```

hosts/m3-atlas/services/AGENTS.md

@@ -0,0 +1,63 @@
+# services/ - m3-atlas Service Configurations
+
+Main server services including Traefik reverse proxy and containerized apps.
+
+## Container Network
+
+- **Network**: `web` (podman network)
+- **Subnet**: `10.89.0.0/24`
+- **Gateway/Postgres**: `10.89.0.1`
+- **DNS Challenge**: GoDaddy via Traefik
+
+## Adding a New Container
+
+1. Pick next available IP from registry (currently: `10.89.0.22`)
+2. Register port in `hosts/common/ports.nix`
+3. Create `containers/<service>.nix`:
+
+```nix
+{config, ...}: {
+  virtualisation.oci-containers.containers."service" = {
+    image = "registry/image:tag";
+    environmentFiles = [config.age.secrets.service-env.path];
+    ports = ["127.0.0.1:PORT:PORT"];
+    volumes = ["service_data:/data"];
+    extraOptions = [
+      "--add-host=postgres:10.89.0.1"
+      "--ip=10.89.0.XX"
+      "--network=web"
+    ];
+  };
+
+  services.traefik.dynamicConfigOptions.http = {
+    services.service.loadBalancer.servers = [{ url = "http://localhost:PORT/"; }];
+    routers.service = {
+      rule = "Host(`service.domain.com`)";
+      tls.certResolver = "godaddy";
+      service = "service";
+      entrypoints = "websecure";
+    };
+  };
+}
+```
+
+4. Import in `containers/default.nix`
+5. Add secret to `secrets.nix` and root `secrets.nix`
+6. Update IP registry in root AGENTS.md
+
+## Service Files (non-container)
+
+| File | Purpose |
+|------|---------|
+| traefik.nix | Reverse proxy, TLS, entrypoints |
+| postgres.nix | Native PostgreSQL for containers |
+| tailscale.nix | Mesh VPN |
+| gitea.nix | Native Gitea (not containerized) |
+| minio.nix | S3-compatible storage |
+
+## Traefik Patterns
+
+- HTTP redirect to HTTPS: automatic via `web` entrypoint
+- TLS: `certResolver = "godaddy"` (DNS challenge)
+- Auth middleware: `middlewares = ["auth"]` (basic auth)
+- Domain redirects: See `traefik.nix` middlewares