diff --git a/AGENTS.md b/AGENTS.md
index 7492c58..ae54716 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,3 +5,32 @@ DO NOT mess with the system's python
 For Frontend work:
 
 read both Frontend Design related Markdown files on the frontend/ folder
+
+For anything touching e621 endpoints or payloads (posts, pools, tags, users,
+favorites, IQDB, blacklists, uploads), consult the e621 OpenAPI spec first:
+    https://e621.wiki/openapi.yaml
+
+Download it once per session (it is ~450 KB YAML), then grep it for the exact
+path/parameter/schema names instead of guessing:
+
+    curl -sL https://e621.wiki/openapi.yaml -o /tmp/opencode/e621-openapi.yaml
+    grep -n "^  /pools.json" /tmp/opencode/e621-openapi.yaml
+
+Notes learned from the spec (verify before trusting):
+- Index endpoints often return a bare array (e.g. GET /pools.json) while the
+  show endpoint returns the object directly (e.g. GET /pools/{id}.json) — not
+  always wrapped in a named key.
+- Pools index supports search[order] (id_asc, id_desc, name, created_at,
+  post_count), search[name_matches], search[category], search[is_active].
+- Own settings (including user[blacklisted_tags]) are updated with
+  PATCH /users/{id}.json as form-encoded data; /users/me.json returns the user
+  object at the top level.
+
+Project constraints (do not regress):
+- Backend is Django 6 + DRF with token auth (no session auth on the API);
+  MariaDB/Redis come from docker-compose.yml.
+- No server-side media processing: the home server cannot handle it.
+  Compression/optimization runs client-side (WebCodecs + WASM in a worker)
+  and the server only applies the result via POST /api/files/J-x/optimize/.
+- Do not use imgdd; perceptual hashing is imagehash server-side.
+- Chat/messaging features are out of scope.
diff --git a/ROADMAP.md b/ROADMAP.md
index 80a6115..4b297fa 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -161,3 +161,6 @@ Files now stage first and are resolved before entering the library.
 - IQDB and e621 matching depend on e621 credentials being configured; the SPA
   talks to e621 directly for browsing, while the backend e621 client
   (`apps/library/e621.py`) handles metadata matching and batch scans.
+- Anything touching e621 endpoints follows the OpenAPI spec
+  (https://e621.wiki/openapi.yaml) — see AGENTS.md for how to fetch and
+  which response shapes to watch out for.