# Agent-Richtlinien für dieses Projekt

## ⚠️ WICHTIG: Pre-Commit Hooks sind Pflicht

**Jeder Commit MUSS die Pre-Commit Lint-Checks durchlaufen. Niemals `--no-verify` verwenden!**

### Für AI-Agents (Claw etc.):
- Verwende `./scripts/safe-commit.sh "Nachricht"` statt `git commit -m "..."`
- Das Script garantiert dass lint-staged läuft (PHP, HTML, CSS, JS, Prettier)
- Wenn ein Linter fehlschlägt: **Fehler beheben, nicht überspringen!**
- Niemals `git commit --no-verify` verwenden

### Lint-Checks die laufen:
- **PHP:** `php -l` Syntax-Check (via `scripts/lint-php.sh`)
- **HTML:** htmlhint
- **CSS:** stylelint + prettier
- **JS:** eslint + prettier
- **JSON/MD:** prettier

---

## Systemumgebung

- **Betriebssystem: Linux** – Befehle und Pfade sind Linux-kompatibel.

---

## Projektübersicht

- **Statische Landingpage** für **Haus Schleusingen**
- Reines HTML, CSS und JavaScript (kein Framework, kein Build-Step)
- Ausgeliefert über einen **Nginx-Docker-Container** (nginx:alpine)
- Git-Repository: `https://git.home.kies-media.de/greggy/landingpage-haus-schleusingen.git`

### Dateistruktur

| Pfad                        | Beschreibung                                 |
| --------------------------- | -------------------------------------------- |
| `public/index.php`    | Einstiegsseite (PHP-Entry-Point)          |
| `css/haus-schleusingen.css` | Hauptstylesheet                              |
| `js/haus-schleusingen.js`   | Haupt-JavaScript                             |
| `js/masonry.pkgd.min.js`    | Masonry-Layout-Bibliothek (nicht bearbeiten) |
| `fonts/fonts.css`           | Schriftart-Einbindungen                      |
| `bilder/`                   | Bildressourcen                               |
| `nginx.conf`                | Nginx-Konfiguration                          |
| `Dockerfile`                | Docker-Image-Definition (nginx:alpine)       |

---

## Code-Qualität & Linting

### Wichtig: Linting nach jeder Codeänderung durchführen

**Führe nach jeder Codeänderung `npm run lint` aus**, um die Codequalität zu garantieren.

Das Projekt verwendet folgende Tools:

| Werkzeug        | Zweck              | Konfigurationsdatei | Befehl              |
| --------------- | ------------------ | ------------------- | ------------------- |
| **HTMLHint**    | HTML-Linting       | `.htmlhintrc`       | `npm run lint:html` |
| **Stylelint**   | CSS-Linting        | `.stylelintrc.json` | `npm run lint:css`  |
| **ESLint**      | JavaScript-Linting | `eslint.config.js`  | `npm run lint:js`   |
| **Prettier**    | Code-Formatierung  | `.prettierrc`       | `npm run format`    |
| **Husky**       | Git Hooks          | `.husky/pre-commit` | –                   |
| **lint-staged** | Gesteuerte Dateien | `package.json`      | –                   |

Alle Linter auf einmal ausführen:

```powershell
npm run lint
```

### ESLint-Regeln (besonders beachten)

- `no-unused-vars` → **Warnung** (ungenutzte Variablen vermeiden)
- `no-undef` → **Warnung** (nur definierte Variablen verwenden)
- `prettier/prettier` → **Fehler** (Prettier-Formatierung ist Pflicht)
- Globale Variablen: `browser` und `jquery` sind verfügbar
- `*.min.js`-Dateien werden ignoriert (nicht linten/bearbeiten)

### HTMLHint-Regeln

- Tag-Paarung Pflicht (`tag-pair`)
- Tags & Attribute in Kleinschreibung (`tagname-lowercase`, `attr-lowercase`)
- Doctype an erster Stelle (`doctype-first`)
- Eindeutige IDs (`id-unique`)
- `alt`-Attribut bei Bildern Pflicht (`alt-require`)
- `<title>` erforderlich (`title-require`)

---

## Entwicklung

- Kein Build-Step erforderlich – statische Dateien
- Lokaler Entwicklungsserver: `npx serve .` oder VS Code Live Server
- Node.js ≥ 18, npm ≥ 9

## Deployment

```powershell
# Image bauen
docker build -t landingpage-haus-schleusingen .

# Container starten
docker run -d -p 8080:80 -v ${pwd}:/usr/share/nginx/html:ro landingpage-haus-schleusingen
```

Website erreichbar unter: **<http://localhost:8080>**

---

## Wichtige Erkenntnisse

- jQuery wird als globale Bibliothek vorausgesetzt (in ESLint-Konfig definiert)
- Masonry (`masonry.pkgd.min.js`) wird für Layout-Zwecke eingesetzt – **nicht bearbeiten**
- Husky Pre-Commit-Hook führt automatisch lint-staged aus (kein manueller Schritt nötig beim Committen)
- Prettier-Formatierung ist verpflichtend – Code wird bei Commits automatisch formatiert
- Projekt ist `commonjs`-Typ (kein ESM in `package.json`)

---

## Agent-Erkenntnisse (Systemumgebung & Tools)

### Terminal & Encoding (Windows)

- **PowerShell-Encoding-Probleme**: Terminal-Ausgabe über `run_terminal_command` zeigt UTF-8-Zeichen (z. B. deutsche Umlaute) oft falsch an. Die Datei selbst ist korrekt. Immer mit `read_file` statt Terminal-Ausgabe prüfen.
- **Backtick-Konflikt**: PowerShell nutzt Backtick (``) als Escape-Zeichen. Markdown-Backticks in Here-Strings (@"..."@) führen zu Fehlern. Für Dateien mit Backticks stattdessen **Node.js-Skripte** verwenden.
- **Zuverlässige Dateierstellung**: Bei Inhalten mit Sonderzeichen (Umlaute, Backticks, Emojis) Node.js-Skripte (`fs.writeFileSync`) statt PowerShell-Befehle nutzen. Beispiel:
  ```javascript
  const fs = require(`fs`);
  const B = String.fromCharCode(96); // Backtick vermeiden
  const lines = [`Zeile 1`, `Zeile 2`];
  fs.writeFileSync(`datei.md`, lines.join(`\n`), `utf8`);
  ```

### Datei-Tools

- **`read_file`-Anzeigegrenze**: Lange Dateien werden in der Vorschau scheinbar abgeschnitten – die Datei selbst ist vollständig. Mit `run_terminal_command` und `Get-Content -Tail N` das Dateiende prüfen.
- **`create_new_file`-Quoting**: Inhalt darf nicht mit Anführungszeichen beginnen, da diese sonst als Teil des Inhalts übernommen werden. Immer die erstellte Datei verifizieren.
- **`single_find_and_replace`**: Exakte Stringübereinstimmung erforderlich. Zeilenumbrüche und Leerzeichen müssen exakt passen. Vor dem Ersetzen den Dateiinhalt mit `read_file` oder `read_file_range` prüfen.
- **`edit_existing_file`-Encoding**: Kann UTF-8-Zeichen (Umlaute, Sonderzeichen) beschädigen. Für Dateien mit Nicht-ASCII-Zeichen stattdessen Node.js-Skripte verwenden.

### Workflow-Empfehlungen

1. **Dateien lesen**: Immer `read_file` oder `read_file_range` nutzen (nicht Terminal).
2. **Dateien schreiben/ändern**: `edit_existing_file` oder `single_find_and_replace` bevorzugen – aber Vorsicht bei Nicht-ASCII-Zeichen.
3. **Komplexe Dateierstellung**: Node.js-Skript über `create_new_file` + `run_terminal_command` ausführen, danach Hilfsskript löschen.
4. **Terminal-Ausgabe**: Nur für Dateigrößen, Git-Befehle und npm-Skripte nutzen – nicht zur Inhaltsprüfung von Textdateien.