diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f0ec5f3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# AGENTS.md
+
+Project context for AI coding agents (Codex, Antigravity, and any agent that reads `AGENTS.md`).
+
+**The canonical instructions for this repo live in [`CLAUDE.md`](CLAUDE.md). Read it first** — this
+file is a thin pointer plus the must-know essentials so nothing is missed if the reference isn't
+chased. Global cross-project rules (identity, Obsidian vault as source of truth, Gitea-first) come
+from your tool's user-level instructions (`~/.codex/AGENTS.md` / `~/.gemini/GEMINI.md`).
+
+## Essentials (full detail in `CLAUDE.md`)
+
+- **What this is:** deployment config for a live, single-host Docker homelab on a headless Ubuntu
+  server reachable at `ssh ginnoir@valhalla`. ~50 containers in per-domain Portainer-managed stacks.
+  This is **not** application code.
+- **The repo is canonical.** Portainer polls `main` every 5 min and redeploys any app stack whose
+  `stacks/<domain>/*` files changed. Editing here changes nothing until you `git push`.
+- **Deployment channels:**
+  - `stacks/<domain>/*` → git push → Portainer redeploys that stack (≤ 5 min).
+  - `Caddyfile` → git push → runner workflow `scp`s it + reloads Caddy (or `apply-compose.ps1 -Caddy`).
+  - `portainer-compose.yml` / `vault.hcl` → `apply-compose.ps1 -Portainer` (Portainer can't manage itself).
+- **Secrets are committed intentionally.** `.env` and `stacks/*/stack.env` are versioned in this
+  PRIVATE repo. Do **not** scrub or gitignore them.
+- **Line endings:** `.gitattributes` forces LF. Never push CRLF (especially `stack.env`) — stray
+  `\r` breaks values on the Linux host.
+- **Networks:** `edge` is the only reverse-proxy network (Caddy + anything it proxies); `<domain>`
+  nets are per-stack private. Caddy upstreams use container name + container-internal port.
+- **Live ops:** there is no `dc` alias — address services by container name with plain `docker`
+  over SSH, or use the `portainer` MCP server.
+
+See `CLAUDE.md` for the on-host topology, "adding a service" steps, Caddyfile/TLS details, and the
+full list of known quirks.