# AGENTS — GitCover.WebStaticBuilder

Guidelines für KI-Agenten, die an diesem Tool (nicht an einer der GCC/GCBoK-Websites) 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 (per-user-Install unter `~/.local/share/GitCover/webstatic`, optionale System-Installation unter `/opt/GitCover/webstatic`; KMU-fähig).
- **Kein Python.** Einzige externe Build-Abhängigkeit: `npx pagefind` (Suchindex, optional).
- Lizenz: **Apache-2.0** (`LICENSE.md`, `NOTICE`) — explizite Patentlizenz §3 + Retorsionsklausel.

## 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:** `GitCover.WebStaticBuilder` (jede `.cs` in `src/` deklariert ihn; `Program.cs` nutzt `using GitCover.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).

### Author & Urheberschaft (Axel Druschel)
- **Alle Development-Arbeit wird von Axel Druschel ausgeführt** — bei jeder Änderung ist er
  als **Author** zu benennen (Entwickler-Attribution in Artefakten).
- **Git-Identität (commit author):** immer `gc-dev-afjd` / `axel.druschel@gitcover.de`
  (Handle, **nicht** der Klarname). Also:
  `git -c user.name=gc-dev-afjd -c user.email=axel.druschel@gitcover.de commit`.
  Im Repo vorkonfiguriert via `git config user.name/user.email`.
- **Quelldatei-Header `Author:`** nennt den **Klarnamen** `Axel Druschel` (Attribution
  des Urhebers); das steht unabhängig von der Git-Handle-Identität.
- **Apache-2.0-konform:** Die `Copyright`-Zeile in `LICENSE.md`/`NOTICE` und den
  Quelldatei-Headern nennt den **Rechteinhaber** `GitCover Commons gUG (haftungsbeschränkt)` (die
  juristische Person). `Author: Axel Druschel` benennt zusätzlich den Urheber/Entwickler —
  das widerspricht Apache-2.0 nicht (die Lizenz regelt nur die Rechtegewährung
  durch den Rechteinhaber, nicht die Urheberbenennung).
- Quelldatei-Header (kanonisch in `docs/license-header.md`) enthalten daher:
  `Copyright 2026 GitCover Commons gUG (haftungsbeschränkt)` + `Author: Axel Druschel` + `SPDX-License-Identifier: Apache-2.0`.

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

## 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. **`GitCover.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
```