# AGENTS — GCBoK.WebStaticBuilder

Guidelines für KI-Agenten, die an diesem Tool (nicht an der GCBoK-Website) arbeiten.

## Wesen des Projekts
- Eigenständiger **Static-Site-Generator** (C# / .NET 10, kompilierte Konsolen-App, Assembly `webstatic`).
- Früher: Submodul `OSS/build_webstatic` innerhalb der GCBoK-Website (`www/build/`).
  Seit 2026-07 eigenständiges OSS-Tool unter `/opt/GitCover/webstatic` (KMU-fähig).
- **Kein Python.** Einzige externe Build-Abhängigkeit: `npx pagefind` (Suchindex, optional).
- Lizenz: **MIT** (`LICENSE`).

## Build & Verify (kanonisch)
```bash
dotnet build -c Release                              # kompiliert src/ -> bin/Release/net10.0/webstatic.dll
dotnet bin/Release/net10.0/webstatic.dll build --env work --verbose   # Beispiel in webstatic.example/
dotnet bin/Release/net10.0/webstatic.dll serve --port 8000            # lokale Vorschau
```

## Konventionen
- **Namespace:** `GCBoK.WebStaticBuilder` (jede `.cs` in `src/` deklariert ihn; `Program.cs` nutzt `using GCBoK.WebStaticBuilder;`).
- **Packages:** `Markdig`, `YamlDotNet` (Versionen **explizit** gepinnt — CPM ist deaktiviert via `<ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>`).
- **Keine unversionierten `PackageReference`** (führt zu NU1015).
- **Config-Priorität:** CLI-Flags > `webstatic.json` > eingebaute Defaults (`BuildConfig.Defaults()`).
- **Pfade generisch:** nie hartkodiert auf `www/` — alles über `Directories` (aus `BuildConfig.Paths` relativ zum Site-Root).
- **i18n:** UI-Texte über `{{ i18n.<bereich>.<key> }}` in Templates; Daten in `i18n.json`; Substitution via `I18n.cs` (Fallback Englisch).

## Verzeichnisstruktur
`plans/` (Pläne), `docs/` (Anleitungen), `diary/` (Dev-Tagebuch), `src/` (Code),
`tests/` (Tests), `webstatic.example/` (KMU-Vorlage), `install.sh`, `LICENSE`.

## Guardrails
- Umlaute in Prosa verwenden (`ä ö ü ß`), nicht `ae/oe/ue`.
- `§` (nicht ausgeschrieben) für Gesetzesparagraphen.
- **Kein Commit ohne expliziten Wunsch.** Bei Release: signierte Commits.
- `dist/`, `bin/`, `obj/`, `.translation-drafts/` sind gitignored.
- Machine-Translation liefert nur **Entwürfe** (`.translation-drafts/`), nie Auto-Überschreibung.

## Versions-Definition (Definition of Done für Releases)
Die Versionsnummer wird an **drei Stellen synchron** gehalten — ein Release-Commit
muss alle drei aktualisieren, andernfalls warnt `webstatic --version` vor einem
Mismatch:

1. **`README.md`** — Block-Quote `> **Version: X.Y.Z**` direkt unter dem Titel
   (kanonisch; per `git show origin/main:README.md` remote sichtbar)
2. **`GCBoK.WebStaticBuilder.csproj`** — `<Version>X.Y.Z</Version>` (Assembly)
3. **`webstatic --version`** — gibt Assembly-Version aus, vergleicht mit README
   und remote Commit-Hash (`git ls-remote origin HEAD`)

Vor einem Release sind lokal und remote die Version feststellbar, ohne die CLI
aufzurufen:
```bash
git show HEAD:README.md        | head -3   # lokal
git show origin/main:README.md | head -3   # remote
```