diff --git a/CONVENTIONS.md b/CONVENTIONS.md
index 64028e4..8904de2 100644
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -1,23 +1,39 @@
 # CONVENTIONS
 
-Rules ai tools must follow
+Rules for AI coding assistants working in this project. 
 
-## General
-
-- Write code you understand yourself. If you cannot explain a line it doesn't belong here
+## Code style
+- Follow the existing style in whatever file you're reading
+- Run the project's linter after every change and fix all issues
 - No "clever" one-liners if a longer form is clearer
-- Function name says what it does, docstring why
-- No comments that restate the code. Comments say "why" not "what"
+- No comments that restate the code. Comments explain "why" not "what"
 
-## Git
-
-- One logical change per commit
-- Commit message in active voice: "add feature x" NOT "added feature X"
+## Naming
+- Files and directories: snake_case
+- Functions and variables: snake_case
+- Classes: PascalCase
+- Database tables: snake_case, plural
+- No single-letter variable names. Except "i", "j", "k" in loop index
 
+## Patterns
+- Every API endpoint validates input before processing.
+- Errors use the frameworks standard error mechanism. Dont invent your own.
 
 ## What NOT to do
+- Do not add new dependencies without explicit instruction. If proposing a dependency describe it in plain text. Do not install it.
+- Do not refactor adjacent code "while you're at it". Stay within the scope of the request.
+- Do not assume environment variables exist. If a new environment variable is needed state it clearly and add it to '.env.example'
+- Do not suppress type checker or linter errors without a comment explaining why.
+- Do not commit code that fails lint, type check or tests. 
 
-- No new dependencies without discussion (propose to ARCH.md, don't add)
-- Don't mess with code style. Follow what is already there
-- Don't refactor adjacent code "while you're at it"
-- No assumed environment variables without decumenting in ARCH.md
+## Git
+- One logical change per commit
+- Commit messages are in imperative mood, lowercase and max 72 char title.
+- Good: "add email validation to user signup"
+- BAD: "added email validation to user signup"
+- BAD: "fix stuff"
+
+## Testing
+- Test files mirror source structure: "src/users/service.py" -> "tests/users/test_service.py"
+- Mock only external IO boundaries. Never mock our own modules, services or utilities.
+- Every new endpoint needs at minimum one test for the success case and one test for a validation error case.
\ No newline at end of file