diff --git a/AGENTS.md b/AGENTS.md
index eb8bec24..f2c74ddc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,6 +9,22 @@ All work goes into `clawdie-iso`. See `PLAN-UNIFY.md` for the active implementat
 
 ---
 
+## Agent Identity
+
+| Identity | Platform | Capabilities | Restrictions |
+|----------|----------|-------------|--------------|
+| Claude (Linux) | Linux dev machine | Code search, file editing, git push | Cannot build ISO, cannot test on FreeBSD |
+| Codex / FreeBSD agent | FreeBSD host | Build ISO, test firstboot flow | Receives handoff docs |
+| Operator (Sam) | FreeBSD host + Linux | ISO builds, deploys, final review | Human — all commits require approval |
+
+### Linux Agent Constraints
+
+The Linux agent MUST NOT attempt to build the ISO (`./build.sh`, `./build-vps.sh`).
+ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`, `pkg`).
+Instead, guide the operator with exact commands to run on the FreeBSD system.
+
+---
+
 ## System Configuration
 
 **Privilege escalation:** Unified on `sudo` (not doas)
@@ -39,6 +55,32 @@ The GUI installer uses `/tmp/clawdie-install.conf` to pass wizard values to
 
 ---
 
+## Cross-Repo Coordination
+
+Clawdie spans two repos. Changes often require coordinated updates.
+
+| Repo | Purpose | Remote |
+|------|---------|--------|
+| `Clawdie-AI` | Agent runtime, control plane, channels | `git@codeberg.org:Clawdie/Clawdie-AI.git` |
+| `clawdie-iso` | ISO builder, firstboot wizard, installer | `git@codeberg.org:Clawdie/Clawdie-ISO.git` |
+
+When changes span both repos, create a handoff doc in the secondary repo
+listing what needs updating. See `Clawdie-AI/AGENTS.md` for full protocol.
+
+---
+
+## Agent Handoff Documents
+
+Use ephemeral handoff files to transfer context between agents.
+
+- **Name:** `doc/<FEATURE>-HANDOFF.md` or `<FEATURE>-HANDOFF.md` (repo root)
+- **Lifecycle:** Create when handing off, delete when complete
+- **Structure:** Must include task checklist, deletion criteria, results section
+
+See `Clawdie-AI/AGENTS.md` for the full handoff template and protocol.
+
+---
+
 ## Attribution in Commit History
 
 Use attribution in commit messages, not in code comments.