# AGENTS.md – Verhaltensregeln und Projekt-Historie

## Zweck dieses Dokuments

Diese Datei richtet sich an **Coding-Agenten (Claude, Codex u.ä.), die in diesem Repository arbeiten**. Sie definiert:

1. **Verhaltensregeln**, an die sich Agenten halten müssen,
2. **kurze Projekt-Orientierung** (Einstieg, Pfade, Ports),
3. die **Historie signifikanter Änderungen**, soweit sie dokumentationswürdig sind.

---

## 1. Verhaltensregeln für Agenten

### R1 – Änderungen werden ausgeführt, nicht simuliert
Wenn du Tools wie `read_file`, `search_replace`, `bash`, `git commit` verwendest, führen diese **reale Änderungen** am Dateisystem bzw. Git-Repo durch. Es gibt in diesem Projekt **keinen Trockenmodus**. Plane sorgfältig, bevor du ausführst.

### R2 – Nach Plan kommt Ausführung + Verifikation
Nach einem Plan oder einer Simulation muss die Umsetzung **tatsächlich auf dem Zielsystem** erfolgen und **verifiziert** werden:
- Server tatsächlich starten (`python3 web/serve.py`)
- Endpunkte per `curl` oder Browser prüfen
- Nicht auf „sieht richtig aus" bauen, sondern auf tatsächliches Verhalten.

### R3 – Nichts in die Doku schreiben, was nicht existiert
Keine „geplanten" Dateien, Skripte, Endpunkte oder Metriken als existent darstellen. Wenn etwas geplant ist, gehört es in einen klar markierten **„Geplant / TODO"**-Abschnitt — nicht in eine Erfolgs- oder Verifikationstabelle.

### R4 – Keine defensive Selbstdarstellung in Projektdokumenten
In Projekt-Dokumenten (README, AGENTS.md, docs/…) gehört **kein Meta-Text** à la „alle Änderungen wurden tatsächlich durchgeführt" oder „EXPLIZITES SIMULATIONSVERBOT". Solche Beteuerungen sind kein Projektwissen, sondern Agenten-Selbstverteidigung — sie gehören maximal **hierher** (siehe R1, R2), nicht in technische Dokumente.

### R5 – Commits sind atomar und aussagekräftig
Ein Commit = eine logische Änderung. Commit-Message im Stil der bestehenden Historie (`feat:`, `fix:`, `docs:`, `chore:`, Präfix + kurze Beschreibung).

---

## 2. Projekt-Orientierung

### Einstieg

```bash
python3 web/serve.py          # startet Server auf http://localhost:8081
./scripts/cleanup_server.sh   # beendet hängende Instanzen
python3 scripts/validate.py   # validiert Template-Struktur
```

### Relevante Pfade

| Pfad                        | Zweck                                                  |
|-----------------------------|--------------------------------------------------------|
| `web/serve.py`              | HTTP-Server (Port 8081, GET + PUT)                     |
| `web/index.html`            | Single-Page-Frontend                                   |
| `web/templates.json`        | Katalog (wird als `/templates.json` ausgeliefert)      |
| `templates/system/*.json`   | System-Templates                                       |
| `templates/user/*.md`       | User-Templates                                         |
| `scripts/validate.py`       | Template-Validierung                                   |
| `docs/`                     | Weitere technische Dokumentation                       |
| `history/CHANGELOG.md`      | Änderungs-Chronik                                      |

### Endpunkte

| URL                                              | Status | Beschreibung                              |
|--------------------------------------------------|--------|-------------------------------------------|
| `GET /` und `GET /index.html`                    | 200    | Frontend                                  |
| `GET /templates.json`                            | 200    | Katalog (aus `web/templates.json`)        |
| `GET /templates/system/*.json`                   | 200    | System-Templates                          |
| `GET /templates/user/*.md`                       | 200    | User-Templates                            |
| `PUT /templates/...`                             | 200    | Template speichern (Content-Type `text/*`)|

### Routing-Regel (wichtig, nicht intuitiv)

`serve.py` mappt `/templates.json` → `web/templates.json` (der Katalog liegt beim Frontend).
Alle anderen `/templates/...`-Pfade mappen auf `<ROOT>/templates/...` (die eigentlichen Templates).

---

## 3. Bekannte Einschränkungen

- Der Server ist für **Entwicklung** gedacht: synchron, ohne Auth, ohne Path-Traversal-Prüfung (siehe `docs/SECURITY.md`).
- PUT-Endpunkt ist nicht authentifiziert — nur lokal verwenden.

---

## 4. Historie signifikanter Änderungen

Autoritative Quelle bleibt `git log`. Diese Tabelle wird nur für Meilensteine gepflegt, nicht für jeden Commit.

| Datum       | Commit     | Kurzbeschreibung                                                    |
|-------------|-----------|---------------------------------------------------------------------|
| 2026-04-24  | `97fa30b` | fix: WCAG-Kontrast für alle Input-/Textarea-Elemente im JSON-Edit-Modal |
| 2026-04-24  | `18cc40e` | feat: JSON-Edit-Modal nach Schlüssel aufgeteilt + WCAG-Kontrast     |
| 2026-04-24  | `ee1b8f7` | fix: JSON-Editor unterstützt Arrays und Objekte via Textarea        |
| 2026-04-24  | `4d9bc9d` | docs: Klarstellung zur tatsächlichen Tool-Ausführung                |
| 2026-04-24  | `581b728` | docs: Commit-Dokumentation in AGENTS.md ergänzt                     |
| 2026-04-24  | `83117d0` | feat: Editier-Button in Template-Karten + PUT-Endpoint in `serve.py`|
| 2026-04-24  | `8e01dd7` | chore: `templates.json` aktualisiert                                |
| 2026-04-24  | `bd7203b` | docs: Verifikations- und Evidenzabschnitt                           |
| 2026-04-24  | `7a774bb` | feat: Port 8081, Template-Pfade korrigiert, `brainstorming.md`      |
| 2026-04-24  | `cbd48df` | docs: `docs/INDEX.md` angelegt                                      |
| 2026-04-24  | `d788c27` | docs: AGENTS.md mit Dokumentationsverlauf                           |

---

## 5. Geplant / TODO

Noch nicht umgesetzt — bitte nicht als vorhanden dokumentieren, bevor es wirklich existiert:

- [ ] `docs/*.md` inhaltlich ausarbeiten (aktuell nur Stubs).
- [ ] `history/` mit strukturierten Protokoll-Einträgen je Release füllen.
- [ ] Automatischer Server-Neustart (`systemd` oder `pm2`).
- [ ] SSL/HTTPS für Produktionsbetrieb.
- [ ] Docker-Containerisierung.
- [ ] Path-Traversal-Schutz und Auth für den PUT-Endpoint.

---

*Letzte Aktualisierung: 2026-04-24*