diff --git a/AGENTS.md b/AGENTS.md
index 09ed4817..955f4047 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,35 @@
-# CLAUDE.md
+# AGENTS.md
+
+Guidance for any coding agent working in the Officer platform repo. **This is the file with the
+instructions in it**; `CLAUDE.md` beside it only points here. Both exist because the two harnesses
+discover different names — opencode walks the tree for `AGENTS.md` and nothing else, Claude Code for
+`CLAUDE.md` — and one set of instructions must reach both.
+
+## Orientation
+
+Officer is built around **one owner** (user id 1, role `Super Admin`, who bypasses every permission
+check), which since 2026-08-07 also admits **additional accounts holding a strict subset of it**. What
+each may reach is decided by per-role permission grants, resolved on every request.
+
+If a design question turns on "which user", the answer depends on the surface: real for the **app**
+permissions (gitea, music, photos, calendar…), and still always **the owner** for anything that
+executes code or touches the disk — terminal, chat, tasks, files, desktop and browser are
+`kind: 'execution'` and can never be granted. `src/servers/permissions/registry.ts` is the authority.
+
+**Mounting a router without a registry entry makes the server refuse to boot.** Read the Permissions
+section below before adding one.
+
+This repo is one of two. The other, `capabilities/`, holds the agent's tasks, tools and skills as plain
+files, and is where many changes belong — adding or changing a task needs no code change here and no
+restart.
+
+- [`docs/working-on-officer.md`](docs/working-on-officer.md) — the deployment-wide guide: which
+  directory a change belongs in, how to run and verify it, the task system, and the failure modes worth
+  knowing about
+- `CONVENTIONS.md` — component organisation and React patterns, with rationale
+- `TODO.md` — current direction; takes precedence where it disagrees with anything else
+
+Treat the code as the source of truth where anything disagrees with it.
 
 ## Project Overview