electric-horses-infra/Agent.md

# Agent Briefing — electric-horses-infra

Du bist ein AI-Agent der an der Infrastructure-as-Code-Ablage von Electric Horses / Richter & Zech arbeitet.

## Was ist dieses Repo?
**Die versionierte Beschreibung unserer Hetzner-Cloud-Infrastruktur.**
Alles was wir auf Servern laufen lassen (docker-compose-Stacks, Configs, Scripts) ist hier abgebildet — ohne Secrets. Das Repo ist kein Deploy-Mechanismus (wir ziehen nicht automatisch aus Git auf die Server), sondern die **Wahrheit-von-gestern**: was aktuell läuft.

Wenn Server A und dieses Repo unterschiedliche Inhalte zeigen, ist entweder ein Commit noch offen ODER die AI hat manuell am Server gearbeitet und das Repo nicht nachgezogen — letzteres ist ein Bug und muss nachgeholt werden.

## Vor jeder Aktion
1. **Lies `README.md`** — die aktuellen Regeln
2. **Lies `Agent.md`** im betroffenen Stack-Ordner (z.B. `stacks/forgejo/Agent.md`) falls vorhanden
3. **Verstehe den aktuellen Zustand** — `git log --oneline -20` zeigt die letzten Aktionen

## Konventionen

### Commit-Messages
- Auf Deutsch ODER Englisch, konsistent pro Commit
- Konventioneller Prefix (feat / fix / docs / refactor / chore)
- Referenz auf OpenProject wenn anwendbar: `Refs OP#1234`
- Kurz und konkret, Detail in Commit-Body

Beispiele:
```
feat(forgejo): add backup cron script

Refs OP#1119
```

```
fix(eh-search): tighten substring match to 3+ chars

Fixes the "ze" noise issue where 2-char queries matched
in unrelated words. Brand-prefix matches still work.

Refs OP#1112
```

### Secrets — NIEMALS committen
- `.env` immer gitignored
- `.env.example` mit Platzhaltern ist OK
- Wenn du echte Credentials brauchst: sie leben auf dem Server in `/opt/<stack>/.env`
- API-Tokens, Passwörter, Zertifikate: **nie** ins Repo, auch nicht in Comments

### Docker-Compose-Files
- Spiegeln 1:1 den Stand auf dem Server
- Image-Tags sind gepinnt (nicht `:latest`) für Reproduzierbarkeit
- Environment-Variablen immer via `env_file` oder `environment:` mit `${VAR}` Syntax — nie hardcoded

### Docs
- Architektur-Beschreibungen in `docs/architecture/`
- ADRs in `docs/adr/<NNNN>-<slug>.md` mit fortlaufender Nummer
- Runbooks in `docs/runbooks/<topic>.md`
- Markdown-Diagramme mit Mermaid (rendert im Forgejo-Web-UI)

## Verbindung zur realen Infrastruktur

| Stack | Server | Pfad auf Server | Dieses Repo |
|---|---|---|---|
| forgejo | ai-apps (10.0.0.8) | `/opt/ai-apps/forgejo/` | `stacks/forgejo/` |
| eh-search | ai-apps (10.0.0.8) | `/opt/ai-apps/eh-search/` | `stacks/eh-search/` |
| (weitere kommen in folgenden Commits) |

**Workflow bei Änderungen:**
1. AI macht Änderung auf dem Server (`docker-compose.yml` anpassen, restart)
2. AI committet die identische Änderung in dieses Repo
3. User reviewt den Commit im Forgejo Web-UI
4. Bei Problemen: Rollback via `git revert` + manuelles Neudeployen auf dem Server

## Zugang zu Servern während der Arbeit
- `ssh ai-apps` — Hetzner cx22, Private 10.0.0.8, Public 91.98.226.44
- `ssh pegasus` — Hetzner cx33, Private 10.0.0.10 (kein Public IPv4)
- `ssh webmin-kronos` — Hetzner cx32 mit sudo, DNS + Apache Proxy
- `ssh authentik-sso` — Hetzner, Private 10.0.0.7, SSO

Lokale Doku mit Credentials: `/Users/benjaminweinlich/Library/Mobile Documents/com~apple~CloudDocs/AI/IT & Infrastruktur/` (nicht in diesem Repo — das Repo ist public!)

## Dieses Repo ist PUBLIC
Das bedeutet:
- **Nichts** was schützenswert wäre commiten (keine Passwörter, interne Kundendaten, Fahrzeug-VINs außer öffentlich dokumentierten Musterdaten)
- Die README + ADRs können gern "Marketing-tauglich" sein — sie zeigen nach außen wie wir denken und bauen
- Für sensiblere Details ein privates Repo nutzen (evtl. zukünftig `electric-horses-infra-private`)

## OpenProject
- **Projekt:** www.electric-horses.de Relaunch (ID 33)
- **Relevante Phasen:**
  - M6: Site Search (abgeschlossen)
  - M7: Operations & Documentation Foundation
    - M7.1: Forgejo Deployment (#1119) — abgeschlossen
    - M7.2: Erstes Infra-Repo (dieses Repo!)
    - M7.3: ADRs/Runbooks/Guides gespiegelt (dieser Commit)
    - M7.4+: Mirror zu GitHub, rclone backup, weitere Apps

## Related Docs (im Repo)
Ab M7.3 lebt die Doku primär in diesem Repo:
- [`docs/adr/`](docs/adr/) — Architecture Decision Records (6 ADRs aus M7.1)
- [`docs/runbooks/`](docs/runbooks/) — Ops-Runbooks
- [`docs/guides/`](docs/guides/) — Wiederverwendbare Setup-Anleitungen
- [`docs/architecture/`](docs/architecture/) — Topologie + Stack-Inventories

Der lokale iCloud-Ordner `AI/IT & Infrastruktur/` ist ab jetzt sekundär — dort leben nur noch Credentials-Hinweise und Lose-Notizen, die nicht in ein public Repo gehören.
chore(repo): initialize infrastructure-as-code repository - README.md explains scope, conventions, what does / does not belong here - Agent.md is the AI session briefing with workflow rules - .gitignore blocks secrets, runtime data, and build artifacts Refs OP#1119 2026-04-11 22:19:10 +02:00			`# Agent Briefing — electric-horses-infra`

			`Du bist ein AI-Agent der an der Infrastructure-as-Code-Ablage von Electric Horses / Richter & Zech arbeitet.`

			`## Was ist dieses Repo?`
			`Die versionierte Beschreibung unserer Hetzner-Cloud-Infrastruktur.`
			`Alles was wir auf Servern laufen lassen (docker-compose-Stacks, Configs, Scripts) ist hier abgebildet — ohne Secrets. Das Repo ist kein Deploy-Mechanismus (wir ziehen nicht automatisch aus Git auf die Server), sondern die Wahrheit-von-gestern: was aktuell läuft.`

			`Wenn Server A und dieses Repo unterschiedliche Inhalte zeigen, ist entweder ein Commit noch offen ODER die AI hat manuell am Server gearbeitet und das Repo nicht nachgezogen — letzteres ist ein Bug und muss nachgeholt werden.`

			`## Vor jeder Aktion`
			1. Lies `README.md` — die aktuellen Regeln
			2. Lies `Agent.md` im betroffenen Stack-Ordner (z.B. `stacks/forgejo/Agent.md`) falls vorhanden
			3. Verstehe den aktuellen Zustand — `git log --oneline -20` zeigt die letzten Aktionen

			`## Konventionen`

			`### Commit-Messages`
			`- Auf Deutsch ODER Englisch, konsistent pro Commit`
			`- Konventioneller Prefix (feat / fix / docs / refactor / chore)`
			- Referenz auf OpenProject wenn anwendbar: `Refs OP#1234`
			`- Kurz und konkret, Detail in Commit-Body`

			`Beispiele:`
			```
			`feat(forgejo): add backup cron script`

			`Refs OP#1119`
			```

			```
			`fix(eh-search): tighten substring match to 3+ chars`

			`Fixes the "ze" noise issue where 2-char queries matched`
			`in unrelated words. Brand-prefix matches still work.`

			`Refs OP#1112`
			```

			`### Secrets — NIEMALS committen`
			- `.env` immer gitignored
			- `.env.example` mit Platzhaltern ist OK
			- Wenn du echte Credentials brauchst: sie leben auf dem Server in `/opt/<stack>/.env`
			`- API-Tokens, Passwörter, Zertifikate: nie ins Repo, auch nicht in Comments`

			`### Docker-Compose-Files`
			`- Spiegeln 1:1 den Stand auf dem Server`
			- Image-Tags sind gepinnt (nicht `:latest`) für Reproduzierbarkeit
			- Environment-Variablen immer via `env_file` oder `environment:` mit `${VAR}` Syntax — nie hardcoded

			`### Docs`
			- Architektur-Beschreibungen in `docs/architecture/`
			- ADRs in `docs/adr/<NNNN>-<slug>.md` mit fortlaufender Nummer
			- Runbooks in `docs/runbooks/<topic>.md`
			`- Markdown-Diagramme mit Mermaid (rendert im Forgejo-Web-UI)`

			`## Verbindung zur realen Infrastruktur`

			`\| Stack \| Server \| Pfad auf Server \| Dieses Repo \|`
			`\|---\|---\|---\|---\|`
			\| forgejo \| ai-apps (10.0.0.8) \| `/opt/ai-apps/forgejo/` \| `stacks/forgejo/` \|
			\| eh-search \| ai-apps (10.0.0.8) \| `/opt/ai-apps/eh-search/` \| `stacks/eh-search/` \|
			`\| (weitere kommen in folgenden Commits) \|`

			`Workflow bei Änderungen:`
			1. AI macht Änderung auf dem Server (`docker-compose.yml` anpassen, restart)
			`2. AI committet die identische Änderung in dieses Repo`
			`3. User reviewt den Commit im Forgejo Web-UI`
			4. Bei Problemen: Rollback via `git revert` + manuelles Neudeployen auf dem Server

			`## Zugang zu Servern während der Arbeit`
			- `ssh ai-apps` — Hetzner cx22, Private 10.0.0.8, Public 91.98.226.44
			- `ssh pegasus` — Hetzner cx33, Private 10.0.0.10 (kein Public IPv4)
			- `ssh webmin-kronos` — Hetzner cx32 mit sudo, DNS + Apache Proxy
			- `ssh authentik-sso` — Hetzner, Private 10.0.0.7, SSO

			Lokale Doku mit Credentials: `/Users/benjaminweinlich/Library/Mobile Documents/com~apple~CloudDocs/AI/IT & Infrastruktur/` (nicht in diesem Repo — das Repo ist public!)

			`## Dieses Repo ist PUBLIC`
			`Das bedeutet:`
			`- Nichts was schützenswert wäre commiten (keine Passwörter, interne Kundendaten, Fahrzeug-VINs außer öffentlich dokumentierten Musterdaten)`
			`- Die README + ADRs können gern "Marketing-tauglich" sein — sie zeigen nach außen wie wir denken und bauen`
			- Für sensiblere Details ein privates Repo nutzen (evtl. zukünftig `electric-horses-infra-private`)

			`## OpenProject`
			`- Projekt: www.electric-horses.de Relaunch (ID 33)`
			`- Relevante Phasen:`
			`- M6: Site Search (abgeschlossen)`
			`- M7: Operations & Documentation Foundation`
			`- M7.1: Forgejo Deployment (#1119) — abgeschlossen`
			`- M7.2: Erstes Infra-Repo (dieses Repo!)`
chore(agent): update briefings to reflect M7.3 doc mirror Root Agent.md and stacks/forgejo/Agent.md had stale references to "docs live in iCloud, will be mirrored in M7.3". Now M7.3 is done, so the briefings point to docs/adr/ and docs/runbooks/ directly with relative links that render as clickable in the Forgejo web UI. The iCloud folder stays around for loose notes and credentials that cannot go into a public repo, but the primary source of truth for ADRs / runbooks / guides is now this repo. Refs OP#1118 2026-04-11 22:26:24 +02:00			`- M7.3: ADRs/Runbooks/Guides gespiegelt (dieser Commit)`
			`- M7.4+: Mirror zu GitHub, rclone backup, weitere Apps`

			`## Related Docs (im Repo)`
			`Ab M7.3 lebt die Doku primär in diesem Repo:`
			- [`docs/adr/`](docs/adr/) — Architecture Decision Records (6 ADRs aus M7.1)
			- [`docs/runbooks/`](docs/runbooks/) — Ops-Runbooks
			- [`docs/guides/`](docs/guides/) — Wiederverwendbare Setup-Anleitungen
			- [`docs/architecture/`](docs/architecture/) — Topologie + Stack-Inventories

			Der lokale iCloud-Ordner `AI/IT & Infrastruktur/` ist ab jetzt sekundär — dort leben nur noch Credentials-Hinweise und Lose-Notizen, die nicht in ein public Repo gehören.