diff --git a/AGENTS.md b/AGENTS.md
index 43efcbc..43a8cfe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,6 +45,20 @@ Do not add endpoints beyond these without a concrete stated need.
 - Readable on small screens without zooming
 - Fast on a low-power ARM CPU — no heavy rendering, no large payloads
 
+## Frontend Conventions
+
+**JS file scoping:** each feature gets its own file. Global app behaviour goes in
+`global-shortcuts.js`. Feature-specific logic gets its own file (e.g. `editor.js`).
+Do not inline JS in the template or consolidate unrelated features into one file.
+
+**Keyboard shortcuts:** `ALT+SHIFT` is the established modifier for all application
+shortcuts — it avoids collisions with browser and OS bindings. Do not use other
+modifiers for new shortcuts.
+
+**Editor toolbar:** buttons use `data-action` (maps to a JS action function) and
+`data-key` (the `ALT+SHIFT+KEY` shortcut letter). Adding a `data-key` to a button
+automatically registers its shortcut — no extra wiring needed.
+
 ## Auth
 - Basic auth is sufficient — this is a personal tool on a private VPN
 - Do not over-engineer access control