diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..af7652a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,130 @@
+# Agent Guidelines for Docker Infrastructure Monorepo
+
+## Repository Structure
+
+This is a Docker Compose monorepo for personal infrastructure hosting. The main focus is Docker services, with local tools in `local/`.
+
+### Core Infrastructure
+- `frontend/` - Cloudflare Tunnel (cloudflared/) and Traefik reverse proxy (traefik/)
+- `backend/` - Core data services (postgres/, redis/)
+- `mgmt/` - Management tools (portainer/, gitea/, grafana/, prometheus/, vaultwarden/, nextcloud/, authentik/)
+- `webapp/` - Applications (n8n/, navidrome/, it-tools/, openwebui/, qbittorrent/, super-productivity/)
+- `templates/` - Configuration templates
+- `remote/` - Remote access utilities
+
+### Local Tools
+- `local/openclaw/` - WhatsApp gateway CLI (Node.js project, see its own AGENTS.md)
+
+## Docker Commands
+
+### Managing Services
+
+```bash
+# Start a service
+cd <service-path> && docker compose up -d
+
+# Stop a service
+cd <service-path> && docker compose down
+
+# View logs
+cd <service-path> && docker compose logs -f
+
+# Restart a service
+cd <service-path> && docker compose restart
+
+# Update/pull latest images
+cd <service-path> && docker compose pull && docker compose up -d
+```
+
+### Network Architecture
+
+- **Traefik** (frontend/traefik/) - Reverse proxy and load balancer
+- **Cloudflared** (frontend/cloudflared/) - Cloudflare Tunnel for secure external access
+- Services use Docker networks defined in their compose.yml files
+- No port forwarding required on home router
+
+## Service Configuration
+
+### Environment Variables
+- Copy `.env.example` to `.env` and fill in values
+- Never commit `.env` files (gitignored)
+- Use `.secrets/` directory for sensitive files (gitignored)
+
+### Traefik Routing
+Services exposed via Traefik use labels in compose.yml:
+- `traefik.enable=true`
+- `traefik.http.routers.<name>.rule=Host(`service.domain.com`)`
+
+### Volume Mounts
+- Data volumes mounted to local directories (e.g., `./data`, `./config`)
+- Some services use named Docker volumes
+- Backup important data directories regularly
+
+## Working with OpenClaw (local/openclaw/)
+
+This is a TypeScript Node.js 22+ project with its own tooling. If you need to work on it:
+
+```bash
+cd local/openclaw/
+
+# Install and build
+pnpm install
+pnpm build
+
+# Test commands
+pnpm test                    # Run all tests
+pnpm test -- src/path/file.test.ts   # Run single test
+pnpm test:coverage          # Run with coverage
+pnpm test:e2e              # Run e2e tests
+
+# Lint and format
+pnpm lint
+pnpm lint:fix
+pnpm format
+pnpm format:fix
+
+# Pre-commit: pnpm lint && pnpm build && pnpm test
+```
+
+For full OpenClaw guidelines, see `local/openclaw/AGENTS.md`.
+
+## Code Style Guidelines
+
+### Docker Compose
+- Use `compose.yml` (not docker-compose.yml)
+- Keep services focused and minimal
+- Use environment files for configuration
+- Mount volumes for persistent data
+
+### Scripts
+- Shell scripts in `scripts/` directories
+- Use `#!/bin/bash` or `#!/bin/sh` shebang
+- Make scripts executable with `chmod +x`
+
+### Python (local tools)
+- Type hints preferred
+- Use `pyproject.toml` for configuration
+- Virtual environments for dependencies
+
+### TypeScript (OpenClaw only)
+- ESM modules (`"type": "module"`)
+- Use `node:` prefix for Node.js built-ins
+- Add `.js` extension to imports (e.g., `from "./file.js"`)
+- PascalCase for types, camelCase for functions
+- Run `pnpm lint` before commits
+
+## Security Best Practices
+
+- **NEVER read, access, or attempt to open `.env` files or `.secrets/` directories** - These contain sensitive data
+- `.env` and `.secrets/` directories are gitignored everywhere
+- Never commit credentials, API keys, or certificates
+- Use Cloudflare Tunnel for external access (no port forwarding)
+- Placeholders in documentation (e.g., `user@example.com`)
+- Credentials stored outside repo in standard locations
+
+## Git Conventions
+
+- Conventional commit messages (e.g., `service: add health check`)
+- Group related changes by service
+- Don't mix unrelated service changes in one commit
+- Test Docker services start correctly after changes