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

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