diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..42cbb4f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# selfhosted2
+
+## Machines
+
+| Name | Role | OS | LAN IP | WG IP | SSH user |
+|------|------|----|--------|-------|----------|
+| hector | Dev machine (this one) | Linux Mint Mate | — | — | — |
+| agge | Backend server | Ubuntu Server | 192.168.1.188 | 10.0.0.2 | tebarbi |
+| raspen | VPS / reverse proxy | Raspberry Pi OS Lite | 192.168.1.187 | 10.0.0.1 | rasput |
+
+## Architecture
+
+All traffic goes through **raspen** (single entry point):
+- nginx in Docker (`vps/docker-compose.yml`) terminates SSL and reverse proxies
+- WireGuard sidecar container encrypts traffic to agge
+- All backend services bind to `10.0.0.2` only (tunnel-only access)
+
+## Services
+
+| Domain | Service | Backend | Via raspen |
+|--------|---------|---------|------------|
+| git.home | Gitea | agge:10.0.0.2:3000 (HTTP), :2222 (SSH) | HTTPS :443, TCP :2222 |
+| nc.home | Nextcloud | agge:10.0.0.2:8080 | HTTPS :443 |
+| pg.home | PostgreSQL | agge:10.0.0.2:5432 | TCP :5432 |
+| raspen.home | Static page | Served directly by nginx | HTTP/HTTPS |
+
+## Repo structure
+
+- `backend/docker-compose.yml` — agge stack (postgres, nextcloud, gitea, postgres_remote)
+- `vps/docker-compose.yml` — raspen stack (wireguard sidecar + nginx)
+- `vps/nginx/conf.d/` — HTTP/HTTPS proxy configs
+- `vps/nginx/stream.d/` — TCP stream proxy configs (postgres, gitea ssh)
+- `vps/wireguard/wg_confs/` — WireGuard tunnel config
+- `.env.example` — template for secrets (real `.env` is gitignored)
+
+## Git remote
+
+```
+ssh://git@git.home:2222/scoot/selfhosted2.git
+```
+
+## Password management
+
+See `.env.example` for required variables. Real `.env` lives on hector and a copy on agge (`chmod 600`). To rotate: generate with `openssl rand -base64 18`, update `.env`, run `ALTER USER` in the container.
diff --git a/opencode.json b/opencode.json
index 5bd3ab5..5e23387 100644
--- a/opencode.json
+++ b/opencode.json
@@ -1,8 +1,9 @@
 {
   "$schema": "https://opencode.ai/config.json",
-   "permission": {
-        "bash": "ask",
-        "external_directory": "ask"
-        }
- }
+  "instructions": ["AGENTS.md"],
+  "permission": {
+    "bash": "ask",
+    "external_directory": "ask"
+  }
+}