kader bestanden toegevoegd

AGENTS.md

@@ -0,0 +1,202 @@
+# AGENTS.md
+
+## Project
+
+Rename-MVP
+
+Minimalistische webapplicatie voor het hernoemen van TV-series bestanden op basis van metadata van TheTVDB.
+
+Technologie:
+
+- Python
+- FastAPI
+- Rootless Podman
+- SQLite
+- TheTVDB API v4
+
+Project root:
+
+/home/kodi/.config/rename-mvp
+
+
+---
+
+# AI Agent Governance
+
+Dit project wordt ontwikkeld met behulp van AI-agents (bijvoorbeeld Codex).
+
+Agents mogen code schrijven en aanpassen, maar **moeten zich strikt houden aan de regels in dit document**.
+
+Het primaire doel is **stabiliteit van het systeem**.
+
+
+---
+
+# Absolute Rules
+
+Agents mogen NOOIT:
+
+- bestaande API responses wijzigen
+- bestaande endpoints verwijderen
+- SAFE FILES aanpassen zonder expliciete toestemming
+- projectstructuur wijzigen
+- code buiten deze repository aanpassen
+- andere Podman containers aanpassen
+- systeemconfiguratie wijzigen
+- Agents mogen geen wijzigingen maken die het contract in contracts/API_GOLDEN.md breken.
+- Agents mogen geen refactors of verbeteringen uitvoeren die niet expliciet gevraagd zijn.
+
+Agents mogen alleen werken **binnen deze repository**.
+
+
+---
+
+# SAFE FILES
+
+De volgende bestanden zijn kritisch en mogen alleen aangepast worden na expliciete bevestiging van de gebruiker:
+Deze bestanden bevatten infrastructuur en API-contracten.
+
+app/services/tvdb_auth_service.py
+container/Containerfile
+requirements.txt
+contracts/API_GOLDEN.md
+AGENTS.md
+CHANGE_POLICY.md
+SAFE_FILES.md
+docs/ARCHITECTURE.md
+
+---
+
+# Escalated Execution
+
+Agents mogen escalated execution gebruiken voor:
+
+- podman build
+- podman run
+- curl tests
+- project builds
+- dependency install
+- bestanden aanmaken of aanpassen binnen dit project
+
+Agents mogen escalated execution **niet gebruiken voor**:
+
+- systeemupdates
+- firewall wijzigingen
+- systemd configuratie
+- container prune
+- docker/podman cleanup
+- andere containers
+
+
+---
+
+# Development Workflow
+
+Elke wijziging moet deze stappen volgen:
+
+1 analyseer de wijziging  
+2 beschrijf welke bestanden worden aangepast  
+3 implementeer wijziging  
+4 voer regressietests uit  
+5 voer feature tests uit  
+
+---
+
+# Testing Policy
+
+Automatische tests zijn verplicht voor elke wijziging.
+
+Na iedere wijziging moet het volgende script worden uitgevoerd:
+
+./regression_tests.sh
+
+Dit script valideert:
+
+- API health endpoint
+- TVDB auth-status endpoint
+- TVDB search endpoint
+
+Als een regressietest faalt moet de wijziging worden teruggedraaid.
+
+---
+
+# Feature Test Policy
+
+Nieuwe functionaliteit moet minimaal drie tests bevatten.
+
+Agents moeten hiervoor het volgende script als basis gebruiken:
+
+./feature_test_template.sh
+
+De template moet worden aangepast zodat deze:
+
+- de nieuwe endpoint of functionaliteit test
+- de JSON response valideert
+- controleert dat bestaande functionaliteit niet breekt
+
+De template zelf is alleen een startpunt en moet per feature worden aangepast.
+
+
+---
+
+# Regression Tests (verplicht)
+
+Regressietests mogen **geen nieuw TVDB-token forceren**.
+
+De volgende tests moeten altijd slagen:
+
+curl 127.0.0.1:8085/api/health  
+curl 127.0.0.1:8085/api/tvdb/auth-status  
+curl "127.0.0.1:8085/api/tvdb/search?q=elsbeth"
+
+Als een van deze tests faalt moet de wijziging worden teruggedraaid.
+
+
+---
+
+# Handmatige Auth Test
+
+De volgende endpoint forceert een nieuwe login en mag **niet in automatische regressietests worden gebruikt**:
+
+curl -X POST 127.0.0.1:8085/api/tvdb/login
+
+Deze endpoint is alleen bedoeld voor debugging.
+
+
+---
+
+# Feature Tests
+
+Nieuwe functionaliteit moet minimaal drie tests bevatten.
+
+
+---
+
+# Security Rules
+
+Agents moeten altijd:
+
+- path traversal voorkomen
+- MEDIA_ROOT restricties respecteren
+- rename preview afdwingen
+- secrets niet loggen
+
+
+---
+
+# Logging Rules
+
+Agents mogen nooit loggen:
+
+- API keys
+- tokens
+- environment secrets
+
+
+---
+
+# Design Principle
+
+Stability over speed.
+
+Het doel is een stabiele backend, geen snelle refactors.