diff --git a/docs/CLAUDE.dist.md b/docs/CLAUDE.dist.md
index 0945a88ca..9398c5dcf 100644
--- a/docs/CLAUDE.dist.md
+++ b/docs/CLAUDE.dist.md
@@ -650,6 +650,12 @@ async on_load() {
 - **`$quoted="string"`** → String literal
 - **`$unquoted=expression`** → JavaScript expression
 - **`$sid="name"`** → Scoped element ID
+- **`attr="<%= expr %>"`** → HTML attribute with interpolation
+
+**Key restrictions:**
+- **`<Define>` attributes are static** - No `<%= %>` on the `<Define>` tag. For dynamic attributes on the root element, use inline JS: `<% this.$.attr('data-id', this.args.id); %>`
+- **`$prefix` = component args, NOT HTML attributes** - `<My_Component $data-id=123 />` creates `this.args['data-id']`, not a `data-id` DOM attribute
+- **Conditional attributes use if-statements** - `<% if (cond) { %>checked<% } %>` not ternaries
 
 ### Component Access