diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bc57355
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+# boxen
+
+- Secrets live in `host_vars/*.sops.yml`. Never read `.envrc`; it loads secrets.
+- Run playbooks with `--limit <host>`. The shared ones in `playbooks/` target
+  only the limited hosts and match nothing without it.
+- Don't run ad-hoc commands against hosts. Ask for the fact instead.
+- Keep evergreen documentation, meaning how things work now, in `docs/`.
+  Update it in the same change that makes it stale. Dated write-ups go in
+  `docs/<host>/YYYY-MM-DD-slug.md`.
+- Commit scope is the directory the change lives in (`lotus-land-story:`).
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md