move to a seperate docs directory

docs/ARCH.md

@@ -0,0 +1,43 @@
+# ARCH - [project name]
+
+Architectural decisions and their reasoning. What components are used, how will they communicate, what libraries are chosen...
+
+## Overview
+
+Short description of what we are building and its structure. 3-5 sentences.
+
+## Tech stack
+
+Brief description of technologies to be used.
+
+Example:
+- Pyton 3.11+, Async support required
+- Pytest 8.x, Testing
+
+## Commands
+
+- Lint: "ruff check src/"
+- Test: "pytest tests/ -x --tb=short"
+
+## File structure
+
+Example:
+src/
+  main.py
+  config.py
+
+tests/
+  test_main.py
+
+
+## architectural decisions.
+
+One section per non-obvious decision. What we choose, what we rejected, why. 
+
+Example:
+### Polling vs events
+- Decision: Polling every 10s
+- Options: Using interrupts
+- Why?: More simple to implement.
+
+

docs/CONVENTIONS.md

@@ -0,0 +1,39 @@
+# CONVENTIONS
+
+Rules for AI coding assistants working in this project. 
+
+## 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
+- No comments that restate the code. Comments explain "why" not "what"
+
+## 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. 
+
+## 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.

docs/JOURNAL.md

@@ -0,0 +1,7 @@
+# JOURNAL
+
+Write a couple of sentences after every session. NOT AI GENERATED. Forces you to articulate what was done and helps to restore context after returning to the project a week later.
+
+Format: date + what was done + why + what's next
+
+## YYYY-MM-DD

docs/SPEC.md

@@ -0,0 +1,35 @@
+# SPEC - [project name]
+
+This file defines WHAT the project does. 
+
+## Goal
+
+One or two sentences about what this project will solve and for who. 
+
+## Acceptance criteria
+
+Project is ready when following concrete criteria are met and tested:
+
+- [ ] [criteria 1]
+- [ ] [criteria 2]
+
+## Constraints
+
+Technical boundaries and limitations:
+
+- Constraint 1
+- Constraint 2
+
+## Out of scope
+
+What is not part of this project:
+
+- Out of scope 1
+- Out of scope 2
+
+## Invariants
+
+Things that must never be broken:
+
+- Invariant 1
+- Invariant 2

docs/TESTS.md

@@ -0,0 +1,4 @@
+# TESTS
+
+Test cases written in my own words. AI tools should read and implement tests written here in natural language.
+