# 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.