diff --git a/AGENTS.md b/AGENTS.md
index e928f57e..277cc9e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,6 +56,29 @@ were name-only across ALL libraries. Fixed; do not regress.
 - Analytics day-buckets must bucket in the user's timezone
   (`CreatedAt.In(loc)`), and date-range end bounds must be end-of-day.
 
+## Known gotchas (do not relearn)
+
+1. **templ does NOT interpolate `{ expr }` inside quoted attribute
+   values** — it emits the literal text. `x-init="f('{ col.ID }')"`
+   shipped a request to `/api/collections/{ collection.ID }` found by
+   the request logs; the whole attribute value must BE an expression:
+   `x-init={ "f('" + col.ID + "')" }`. Note
+   `class="theme-{ user.Theme }"` has always been literal (harmlessly
+   masked by the JS theme engine).
+2. **SettingsRegistry caches**: writes must go through the settings
+   API (Reload on save). Direct SQL writes to system_settings leave
+   the cache stale until the next API-path write — never "preview"
+   rule changes via psql and expect them applied (2026-10-14: a live
+   curl test flip looked ignored until the API path was used).
+3. **User collections are not dashboard sections**: nothing sets
+   collection show_on_dashboard for user rows, and GetDashboardSections
+   skips empty user sections. Collection detail (JSON + SSR) must NOT
+   route user rows through the dashboard-section path — a 7ce7321
+   regression did exactly that (static detail without library_id
+   returned zero books until 0a7fbd6). Only real system query types
+   (continue-reading etc.) route there; `query_type='filter'` is the
+   schema DEFAULT on every user row, not a query type.
+
 ## Conventions (absorbed from the retired PROJECT_GUIDELINES.md —
 ## only the rules that still matched reality)