From 8de8883acff0e0b38fe3294fefc3b944866ca221 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Wed, 14 Oct 2026 12:00:33 -0400
Subject: [PATCH] docs(agents): templ attribute-interpolation, settings-cache,
 collection-routing gotchas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the smart-collections build: templ emits quoted attribute values
literally (whole-attribute expressions required — the rules page
shipped '/api/collections/{ collection.ID }' until proven via request
logs); SettingsRegistry only reloads through the settings API (direct
SQL writes look ignored); and user collections must never route through
the dashboard-section path (query_type='filter' is a schema DEFAULT,
not a query type — the 7ce7321 static-detail regression).
---
 AGENTS.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

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)