# AGENTS.md

Dieses Dokument definiert projektlokale Leitplanken fuer Menschen und Agenten, die an diesem Repo arbeiten.

## 1) Architekturprinzipien

- Trennung der Verantwortungen beibehalten:
  - `internal/*svc`: fachliche Logik (Template, Onboarding, Draft, Build, Mapping).
  - `internal/store/*`: Persistenz-Adapter.
  - `internal/httpserver/handlers`: Transport/UI-Glue, keine schwere Fachlogik duplizieren.
- Draft-/Review-/Build-Flow ist der zentrale Kontrollpfad.
- Persistenz ist Teil der Kernlogik, nicht optionales Nebenprodukt.
- Kleine, nachvollziehbare Aenderungen statt grosser Umbauten ohne klaren Nutzen.

## 2) Aktueller Scope

- AI-Template-Sync, Discovery/Onboarding und bearbeitbare Manifest-Felder.
- Draft-Intake, Draft-Bearbeitung und Statuswechsel (`draft`, `reviewed`, `submitted`).
- Externer Draft-Intake-Vertrag (`POST /api/drafts/intake`) fuer Stammdaten plus optionalen Website-/Stilkontext.
- Build-Start aus geprueften Daten, Polling und Editor-URL-Abruf.
- SQLite als Default-Datenhaltung fuer lokalen Betrieb.

## 3) Bewusst noch nicht machen

- Keine direkte Leadharvester->Build-Abkuerzung in der QC App.
- Kein unkontrolliertes Auto-Building ohne Draft-/Review-Schritt.
- Keine grossen Security-Umbauten im Vorbeigehen; Security wird gezielt spaeter gehaertet.
- Keine unnoetigen Architekturverschiebungen, die bestehende Build-/Draft-/Review-/Persistenzlogik verbiegen.

## 4) Leadharvester-Integration (Zielbild)

- Leadharvester liefert Upstream-Daten (Stammdaten + optional Website-Zusammenfassung).
- Uebergabe in die QC App erfolgt ueber Draft-Intake und anschliessende Review.
- Die QC App bleibt verantwortliche Stelle fuer Mapping, Template-Logik, Review und finalen Build.

## 5) Spaetere LLM-Features

- LLM-Unterstuetzung darf nur als Vorschlagssystem eingefuehrt werden (reviewbar/ueberschreibbar).
- Vorschlaege muessen `businessType` und ein Stilprofil (Tone/Style) beruecksichtigen.
- Kein LLM-Bypass des Review-Gates.

## 6) Doku-Pflegepflicht bei Aenderungen

Bei jeder relevanten Verhaltensaenderung:
- README kurz und aktuell halten (Ist-Stand, Start, Kernfluss).
- `docs/TARGET_STATE_AND_ROADMAP.md` aktualisieren (Zielbild/Roadmap).
- Roadmap-Status mit diesen Markern pflegen:
  - `[x]` erledigt
  - `[-]` teilweise offen
  - `[ ]` offen

Wenn ein Feature nur geplant ist, darf es nicht als fertig dokumentiert werden.

## 7) Umgang mit `data/qctextbuilder.db`

- `data/qctextbuilder.db` ist versionierbar, aber kein normales Immer-mitcommitten-Artefakt.
- Standardregel: bei normalen Code-/Doku-Commits **nicht** automatisch mit aufnehmen, auch wenn sich die Datei geaendert hat.
- Wenn ein reproduzierbarer lokaler Zustand bewusst festgehalten werden soll, darf die DB gezielt als eigener Snapshot-Commit aufgenommen werden.
- Snapshots der DB bewusst separat von Code-Commits halten, damit Aenderungen an Laufzeitdaten klar von Codeaenderungen getrennt bleiben.