docs: add git workflow howto (remotes, PR merge, deploy)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/howto-git-workflow.md

@@ -0,0 +1,142 @@
+# Git-Workflow: Remotes, Branches, Merges
+
+Letzte Aktualisierung: 2026-06-23
+
+Dieses Projekt hat zwei Git-Remotes mit unterschiedlichen Rollen:
+
+| Remote | URL | Zweck |
+|--------|-----|-------|
+| `github` | `https://github.com/theurj/breadcrumb-the-shire.git` | CI/CD (GitHub Actions) — hier wird deployed |
+| `origin` | `https://onion.breadcrumb-online.de/fa/...` | Gitea — internes Repo, Pull Requests von Kollegen |
+
+Alle Deployments laufen über `github`. Auf `origin` (Gitea) wird **nicht automatisch gepusht**.
+
+---
+
+## Remotes anzeigen
+
+```bash
+git remote -v
+```
+
+Ausgabe:
+```
+github  https://github.com/theurj/breadcrumb-the-shire.git (fetch)
+github  https://github.com/theurj/breadcrumb-the-shire.git (push)
+origin  https://fa:TOKEN@onion.breadcrumb-online.de/fa/breadcrumb-the-shire.git (fetch)
+origin  https://fa:TOKEN@onion.breadcrumb-online.de/fa/breadcrumb-the-shire.git (push)
+```
+
+---
+
+## Änderungen auf GitHub deployen
+
+```bash
+git push github main
+```
+
+Löst GitHub Actions aus (CI + Deploy). Niemals `git push` ohne `github` — sonst landet es nur in Gitea.
+
+---
+
+## Pull Request eines Kollegen aus Gitea übernehmen
+
+### 1. Offene PRs in Gitea anzeigen
+
+```bash
+curl -s "https://fa:TOKEN@onion.breadcrumb-online.de/api/v1/repos/fa/breadcrumb-the-shire/pulls?state=open" \
+  | python -c "import sys,json; [print(f'PR #{p[\"number\"]}: {p[\"title\"]} | branch: {p[\"head\"][\"label\"]} | by: {p[\"user\"][\"login\"]}') for p in json.load(sys.stdin)]"
+```
+
+### 2. Fork des Kollegen als Remote hinzufügen
+
+```bash
+git remote add tbh "https://fa:TOKEN@onion.breadcrumb-online.de/tbh/breadcrumb-the-shire.git"
+```
+
+Den Remote-Namen (`tbh`) einmalig hinzufügen — bei weiteren PRs desselben Kollegen entfällt dieser Schritt.
+
+### 3. Branch holen und Commits prüfen
+
+```bash
+git fetch tbh feature/security-checks
+git log tbh/feature/security-checks --oneline --not origin/main
+```
+
+### 4. Geänderte Dateien im Überblick
+
+```bash
+git diff origin/main...tbh/feature/security-checks --stat
+```
+
+### 5. Branch in main mergen
+
+```bash
+git merge tbh/feature/security-checks --no-ff -m "feat(security): merge security checks module"
+```
+
+`--no-ff` erzwingt einen Merge-Commit, damit der Branch-Ursprung im Log sichtbar bleibt.
+
+### 6. Auf GitHub pushen
+
+```bash
+git push github main
+```
+
+---
+
+## Eigene Änderungen committen und pushen
+
+```bash
+# Bestimmte Dateien stagen (nie git add -A, könnte .env miterfassen)
+git add modules/helpdesk/pages/helpdesk/handovers/_form.phtml
+
+# Committen
+git commit -m "fix(helpdesk): describe what and why"
+
+# Deployen
+git push github main
+```
+
+---
+
+## Status und Log
+
+```bash
+# Aktueller Zustand (geänderte / ungetrackte Dateien)
+git status
+
+# Letzte Commits
+git log --oneline -10
+
+# Alle Branches (lokal + remote)
+git branch -a
+
+# Änderungen zwischen lokalem main und GitHub
+git diff github/main...main --stat
+```
+
+---
+
+## Neuen Kollegen-Fork als Remote hinzufügen
+
+```bash
+git remote add <name> "https://fa:TOKEN@onion.breadcrumb-online.de/<username>/breadcrumb-the-shire.git"
+```
+
+Beispiel für Benutzer `mia`:
+```bash
+git remote add mia "https://fa:TOKEN@onion.breadcrumb-online.de/mia/breadcrumb-the-shire.git"
+git fetch mia feature/my-feature
+git merge mia/feature/my-feature --no-ff -m "feat(...): merge ..."
+git push github main
+```
+
+---
+
+## Wichtige Regeln
+
+- **Niemals** `git push` ohne Remote-Angabe — Standard-Remote ist `origin` (Gitea), nicht `github`.
+- **Niemals** `git add .` oder `git add -A` — immer Dateien explizit benennen (verhindert, dass `.env` oder `db_export.sql` committet wird).
+- Jede Änderung sofort committen, nicht sammeln.
+- `db_export.sql` ist gitignored (oder sollte es sein) — nicht committen.

docs/index.md

@@ -59,6 +59,8 @@ Diese Dokumentation ist nach dem Diataxis-Modell in vier Quadranten gegliedert:
   - Neues Modul erstellen: Scaffold, Manifest, Route, Permission, UI-Slot, Test.
 - `/docs/howto-gitea-required-checks.md`
   - Gitea-Workflow für `qa-required` vorbereiten (Phase 1 enforcement-ready).
+- `/docs/howto-git-workflow.md`
+  - Git-Remotes (Gitea + GitHub), Kollegen-PRs übernehmen, deployen.
 - `/docs/howto-dokumentation-erweitern.md`
   - Regeln für konsistente, wachsende Doku.