diff --git a/AGENTS.md b/AGENTS.md
index 36850511..b3e33df1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,15 @@ stats, toasts, password validation. Anything else that renders app UI
 in TypeScript is a defect; if a templ twin of it exists, one of the two
 must be deleted.
 
+**Documented exception — dashboard sections**: `renderDashboardCollections`
+/ `renderSectionHTML` in `web/src/dashboard.ts` re-render dashboard
+sections from `/api/dashboard/sections` JSON (library switch, settings
+save, refresh button) to preserve the switch fade/transition on a page
+with heavy interactivity. First-paint section markup is still templ
+(Dashboard handler in `internal/router/frontend.go`). This exception is
+deliberate; do not clone it to new pages, and do not "fix" the dashboard
+without restoring a templ-partial fade path first.
+
 ## Library visibility (family-lens rule) — ALWAYS apply
 
 Per-user library visibility (`library_visibility` table, default-ALLOW: