diff --git a/AGENTS.md b/AGENTS.md
index 5afb834ec..2f07b1545 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -105,6 +105,35 @@ These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full
 
 When adding a new doc under `docs/`, check `website/.vitepress/config.ts` sidebar config. Sections using `getMarkdownFiles()` are auto-discovered. All other sections need a manual `{ text, link }` entry.
 
+## Sandbox image topology
+
+Fullsend agents run inside sandboxed containers. Two images exist in a
+parent–child hierarchy; which image an agent uses depends on whether it
+needs a compiled-language toolchain.
+
+```
+ghcr.io/nvidia/openshell-community/sandboxes/base   (upstream)
+  └── fullsend-sandbox                                (base sandbox)
+        └── fullsend-code                             (extends base with Go)
+```
+
+| Image | Agents | Run frequency | Key additions over parent |
+|-------|--------|---------------|--------------------------|
+| `fullsend-sandbox` | triage, prioritize, retro | High (most agent runs) | Claude Code, jq, gitleaks, acli, pre-commit, gitlint, tirith, ProtectAI DeBERTa model |
+| `fullsend-code` | code, fix, review | Lower (code/fix are the least-run agents; review runs per-PR) | Go toolchain, scan-secrets, gopls, lychee |
+
+Harness definitions that map agents to images live in
+`internal/scaffold/fullsend-repo/harness/*.yaml` (the `image:` field).
+Image Containerfiles live in `images/sandbox/` and `images/code/`.
+The CI build pipeline is `.github/workflows/sandbox-images.yml`.
+
+**When reviewing CI changes:** If a PR modifies image pulling, caching,
+or pre-warming logic in `action.yml`, consider which agent types are
+affected. Changes that only benefit `fullsend-code` have a smaller blast
+radius (fewer agent runs) than changes to `fullsend-sandbox`. A cache or
+pull optimization may not be worth the complexity if it only helps the
+least-frequently-run agents.
+
 ## Key design decisions made
 
 - **Autonomy model:** Binary per-repo, with CODEOWNERS enforcing human approval on specific paths