diff --git a/AGENTS.md b/AGENTS.md
index 195c857..e6718b7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -136,6 +136,10 @@ Read [the Cursor Cloud environment notes](docs/CURSOR-CLOUD-ENVIRONMENT.md)
 when working in a Cursor Cloud VM: toolchain, the test, validate, and run
 commands, and the `npm install` caveat.
 
+## Org architecture
+
+Org architecture (cross-repo decisions, glossary, why each trust link exists): private repo `melodic-software/architecture`. Repo map: `gh api orgs/melodic-software/properties/values` (system and role per repo). Read it with `gh api repos/melodic-software/architecture/contents/<path>`; on Claude Code on the web, attach it at session start; in CI, check it out with a read-only App token. If access is denied, stop and tell the user.
+
 ## Code Review Rules
 
 Each line names a rule CI does not enforce; the linked file states it in full.