diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a741b67
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# Agent working agreement — Void / homelab
+
+## Documentation policy (standing rule — do not skip)
+
+**Every change, decision, fix, or incident must end up documented in BOTH places before the work is considered done:**
+
+1. **The Void wiki** — the `wiki` space served by the Void. Update the relevant existing page, or create one. This is the human-facing source of truth and what `infra_audit` reads.
+2. **Git** — the code plus an appropriate written artifact (a spec/plan under `docs/superpowers/`, a `CHANGELOG.md` entry, and/or a doc page), committed and **pushed** to Gitea.
+
+Capture **verbose-first** — we consolidate/compress later. Losing information is the only failure mode; over-documenting is fine. Do this proactively as part of finishing a task, not only when asked.
+
+### How — wiki
+Owner token: `OWNER_TOKEN` in `/opt/void-server/.env` on CT 311 (`void-app`, `192.168.1.216`). API on the LAN at `http://192.168.1.216:3000`:
+- Edit a page: `PATCH /api/pages/:id` with `{ "body_md": "…", "title": "…" }`
+- Create a page: `POST /api/spaces/2201a3dd-2d40-425c-a4cf-7f18882a9146/pages` with `{ "slug", "title", "body_md", "parent_id" }`
+- Per-LXC / per-service pages parent under **Hosts & Services** (`ab398d61-805a-46dd-b1ba-6f09374bd7aa`).
+- **Do not** write a contiguous `IP:port` for a remote-site or inactive host — `infra_audit` probes those and will false-flag them.
+
+### How — git
+Commit code + docs together and push to the project's Gitea repo:
+- `void-v2` → `Hynes/Void-Homelab`
+- `farm-timelapse` → `Hynes/farm-timelapse`
+
+Specs/plans live in `docs/superpowers/{specs,plans}/`; user-facing changes get a `CHANGELOG.md` entry.