diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e3bdaaa
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# Project Directory — Agent Guide
+
+Living index page of the Ourpad home lab. Lists self-hosted projects, public services, internal services, infrastructure details, and LXC inventory — single-page reference for the entire homelab.
+
+## Stack
+
+- **Python** 3.11+, **FastAPI**, **uvicorn**
+- **httpx** — proxied API calls to Proxmox and network-status
+- **Frontend:** static HTML/CSS with embedded JS, SVG favicon
+
+## Project Structure
+
+```
+serve.py            # ~300 lines — FastAPI server, static file + API proxy
+index.html          # ~41KB — self-contained HTML with all project/service data
+favicon.svg         # SVG favicon
+README.md
+```
+
+## How to Run
+
+```bash
+python serve.py
+```
+
+Binds to `127.0.0.1` by default (port configurable via `SERVE_PORT` env var).
+
+## Key Architecture
+
+- Serves `index.html` as static content
+- `/api/status` — proxies to internal network-status service for live status checks
+- Proxmox API integration — fetches LXC/VM status from two Proxmox hosts
+- All project/service data embedded directly in `index.html` (no separate data files)
+
+## Production
+
+- **URL:** https://projects.ourpad.casa
+- **Port:** 18834 (default, configurable)
+- **Binds to:** 127.0.0.1 (NPMPlus reverse proxy)
+- **No systemd**
+
+## Environment Variables
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| SERVE_PORT | 18834 | Server listen port |
+
+## Security Note
+
+`serve.py` contains Proxmox admin credentials (base64 encoded). This is internal- only behind NPMPlus proxy. Do not expose directly to the internet.
+
+## Pitfalls
+
+- **Single page** — `index.html` has all data hardcoded; adding a new service requires editing the HTML directly
+- Proxmox credentials embedded in source — use environment-based auth if exposing more broadly
+- No CI/CD — update by editing `index.html` and `serve.py` directly on the server