Instruct the agents

Author: scriptype

AGENTS.md

@@ -11,23 +11,58 @@
 - Keep notes in `notes/` as markdown files named `dd-mm-yy-topic.md`
 
 ## Coding Conventions
+
+### Naming
+- Never shorten self-documentary names unless the short form is also self-documentary and well-known (e.g. `btn`, `el`, `i` are OK; `ct`, `coll`, `sub` are not)
+- Replace magic numbers with named constants
+- Use pronounceable, searchable names
+- Function names must accurately describe the operation, not the caller's intent
+- Prefer domain-specific terms over generic words (e.g. `node` over `item` when the domain calls them nodes)
+- Avoid encodings — don't append prefixes or type information
+
+### Functions
+- Functions should do one thing
+- Prefer fewer arguments (ideally ≤ 3)
+- Functions should have no side effects — do what the name suggests and nothing else
+- Don't use flag arguments; split into separate functions
+
+### Comments
+- Always try to explain yourself in code first; comment only when code can't be clear enough on its own
+- Don't add obvious/redundant comments
+- Don't comment out code — just remove it (version control exists)
+- Use comments for intent, clarification, or warning of consequences
+- Always use standard comment styles, no extra dashes or decorations
+- In multiline comments, add blank lines between logical points
+
+### Structure
 - Respect existing indentation style in each file
 - Keep lines shorter than 80 columns (including comments), but don't break a line just to shave a few characters if it hurts readability
+- Don't break a logical unit of code across lines when it fits on one line
 - No trailing whitespace
-- In multiline comments, add blank lines between logical points
+- Separate concepts vertically with blank lines
+- Related code should appear vertically dense (close together)
+- Declare variables close to their usage
+- Dependent functions should be close to each other
+- Place called functions below their callers (downward direction)
+
+### General
+- Be consistent — if you do something a certain way, do all similar things the same way
+- Avoid negative conditionals (prefer `isActive` over `isInactive`)
+- Encapsulate boundary conditions in one place
+- Don't repeat yourself (DRY), but don't abstract prematurely either
 
 ### JS
 - Avoid semicolons unless absolutely necessary
 - Always use curly braces {} for control structures (if, for, while, etc.), even for single statements
 - For multiline arrow functions without explicit parentheses, always use curly braces with return (e.g., `=> { return ... }`, not `=> expr` spanning lines). Implicit return with parentheses is OK (e.g., `=> ({...})`)
 - Respect default JSHint rules
-- Break logical operator chains (&&, ||) across lines only when significantly long
+- Keep logical operator chains (&&, ||) on one line unless they exceed 80 columns
 - Keep short destructured imports on one line; break across lines only when exceeding 80 columns
 - Keep ternary `?` at end of line, not start of next
 - Always check for unused imports after finishing work on a module
 
 ### CSS
-- Order CSS properties from layout-affecting to cosmetic: positioning → display/layout → box model (padding, border) → typography → background/color → decoration (shadow, opacity) → animation → z-index
+- Order CSS properties from layout-affecting to cosmetic: positioning/z-index → display/layout → box model (padding, border) → typography → background/color → decoration (shadow, opacity) → animation
 - Never use arbitrarily high z-index values; use the lowest value that works
 
 ## Testing

src/cms/server/public/AGENTS.md

@@ -9,5 +9,18 @@
 - `app/components/` holds reusable components
 - Feature-specific modules live in their own folders under `app/components/` (e.g., `app/components/explorePanel/`)
 
+## Coding Conventions
+
+### HTML Templates
+- Extracted sub-template functions should own their
+  wrapper element, not just return inner content
+- Extracted sub-template functions should co-locate
+  their relevant `<style>` block
+
+### CSS
+- Prefix all CSS classes within a component with the
+  component name (e.g. `content-panel-divider`, not
+  `content-divider`)
+
 ## Verification
-- After moving/renaming files or changing imports, check the browser console for errors (server runs on port 8080)
+- After moving/renaming files or changing imports, check the browser console for errors (server runs on port 8080)