Auftragsbuch: 'doku/gitea-skill-doku' angenommen (Ein-Klick-Gate)

docs/skills/gitea-workflow.md

@@ -0,0 +1,146 @@
+# gitea-workflow — Git- und Gitea-REST-API-Workflows
+
+> **Kurz:** Wenn das Repo schreibgeschützt ist (Faden 8 / R2), arbeitet der Agent über einen sauberen Clone in `/tmp` und erstellt einen PR via Gitea-REST-API statt direkt zu pushen.
+
+## Was der Skill tut
+
+Der Skill beschreibt einen alternativen Git-Workflow für Fälle, in denen der direkte Schreibzugriff auf ein Repo blockiert ist (insbesondere das `mission-control-v2`-Repo unter Faden 8/R2). Statt direkt zu committen, wird:
+
+1. Ein frischer Clone in `/tmp` erstellt.
+2. Ein Feature-Branch von `origin/main` abgezweigt.
+3. Änderungen im Clone gemacht, committet, gepusht.
+4. Ein Pull Request via Gitea-REST-API auf `main` erstellt.
+
+Das Ergebnis landet als Vorschlags-Branch auf Gitea und geht über das Auftragsbuch ins Live-System — der Commander muss es annehmen.
+
+## Wann er zum Einsatz kommt
+
+| Situation | Aktion |
+|---|---|
+| Repo hat Schreibschutz (Faden 8 / R2) | Gitea-Workflow (diese Datei) |
+| Neues Projekt wird vorbereitet | `gitea-repo-create.sh` + Gerüst aufbauen |
+| Normaler Repo-Zugriff ist erlaubt | Direkter Git-Workflow (Branch → Commit → Push) |
+
+## Konfiguration
+
+### Zugangsdaten
+
+- **Gitea-URL:** `https://git.tobisniceshomelab.ddnsfree.com`
+- **User:** `Hitonabi`
+- **Token:** In `.git-credentials` oder Config-Files hinterlegt (Scope `write:repository`)
+- **Repo-Anlege-Token:** In `~/.config/gitea/create-token` (dediziertes `write:user`-Token)
+
+### Token-Unterschied
+
+| Token | Ort | Scope | Einsatz |
+|---|---|---|---|
+| Push/PR-Token | `~/.git-credentials` | `write:repository` | Branch-Push, PR erstellen |
+| Repo-Anlege-Token | `~/.config/gitea/create-token` | `write:user` | **Nur** Repo-Anlage über `gitea-repo-create.sh` |
+
+Ein Repo kann **nur** mit dem `write:user`-Token angelegt werden — der Push-Token reicht nicht. Nie per Roh-`curl` erzwingen.
+
+## Arbeitsablauf (Schritt-für-Schritt)
+
+### 1. Sauberen Clone erstellen
+
+```bash
+cd /tmp && rm -rf <repo>-temp && git clone https://USER:TOKEN@git.tobisniceshomelab.ddnsfree.com/USER/<repo>.git <repo>-temp
+```
+
+### 2. Branch von origin/main erstellen
+
+```bash
+cd /tmp/<repo>-temp && git checkout -b <branch-name> origin/main
+```
+
+Branch-Namen mit `/` (z. B. `doku/gitea-skill`) funktionieren.
+
+### 3. Files kopieren, committen
+
+```bash
+cp <quelle> <repo>-temp/<pfad>
+git add <pfad> && git commit -m "<commit-nachricht>"
+```
+
+### 4. Pushen
+
+```bash
+cd /tmp/<repo>-temp && git push origin <branch-name>
+```
+
+### 5. PR via REST API erstellen
+
+```bash
+curl -sL -X POST "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos/<owner>/<repo>/pulls" \
+  -H "Authorization: token <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "<PR-Titel>", "body": "<PR-Body>", "head": "<branch-name>", "base": "main"}'
+```
+
+### 6. Main-SHA abrufen (falls nötig)
+
+```bash
+curl -sL "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos/<owner>/<repo>/git/refs/heads/main" \
+  -H "Authorization: token <TOKEN>"
+```
+
+## Neues Projekt vorbereiten (seit 17.07.2026)
+
+Bei einem neuen Projekt wird nicht nur der Workflow angewendet, sondern das komplette Gerüst gelegt:
+
+1. **Repo anlegen** (privat, initialisiert):
+   ```bash
+   ~/.hermes/scripts/gitea-repo-create.sh <name> "<Kurzbeschreibung>"
+   ```
+   Die letzte Ausgabezeile ist `CLONE <URL>` — diese merken.
+
+2. **Lokal klonen**:
+   ```bash
+   git clone <clone-url> /tmp/<name> && cd /tmp/<name>
+   ```
+
+3. **Dateistruktur aufbauen** (nur das Gerüst):
+   - `README.md` mit Ziel/Scope
+   - `.gitignore` passend zur Sprache
+   - Grundordner (`src/`, `docs/`, `tests/`) mit Platzhaltern
+   - `AGENTS.md` (Projekt-Kontext für spätere Desktop-Arbeit)
+   - Kein fertiger Code — nur das Skelett, das der Commander in Hermes Desktop weiterbaut
+
+4. **Committen + pushen**:
+   ```bash
+   git add -A && git commit -m "Projekt-Gerüst: Struktur + README" && git push
+   ```
+
+5. **Clone-Fallback** (wenn Zielordner schon existiert):
+   ```bash
+   git rm -r --cached . 2>/dev/null; rm -rf .git
+   git init && git remote add origin <url>
+   git fetch origin
+   git checkout -b main origin/main
+   git checkout origin/<branch> -- .
+   ```
+
+6. **Übergeben**: Commander die Repo-URL melden + kurz beschreiben, was vorbereitet wurde.
+
+## Pitfalls
+
+| Falle | Vermeidung |
+|---|---|
+| Blobs direkt über `/git/blobs` erstellen → 404 | Niemals; immer `git add` + Commit nutzen |
+| Push/PR-Token reicht nicht für Repo-Anlage | `gitea-repo-create.sh` mit `write:user`-Token nutzen |
+| Repo-Anlage per Roh-`curl` erzwingen | Nie — Token-Berechtigungen sind serverseitig, das Skript ist der einzige Weg |
+| Grosse Dateien am Stück lesen → Kontext sprengt | Gezielt lesen über Zeilenbereiche (`read_file` mit offset/limit) |
+| Direkt in Live-Checkout schreiben → Faden 8 | Immer im frischen Klon arbeiten, Vorschlagsbranch via PR |
+
+## Konsistenz mit MC2-Konventionen
+
+- **Sprache:** Deutsch, direkt, kein Marketing-Sprech.
+- **Struktur:** Kurze Beschreibung → Wann einsetzen → Konfiguration → Arbeitsablauf → Pitfalls → Konsistenz.
+- **Querverweise:** Verweise auf Faden 8/R2, Auftragsbuch, `gitea-repo-create.sh`.
+- **Tabellen:** Wo sinnvoll (Situationen, Konfiguration, Pitfalls) als Tabelle formatiert.
+- **Code-Blöcke:** Alle Befehle als bash-Code-Blöcke mit klaren Variablen-Platzhaltern.
+- **Keine Secrets:** Tokens werden referenziert (Ort), nicht ausgeschrieben.
+
+---
+
+_Diese Datei wurde als Skill-Dokumentation im MC2-Repo erstellt. Sie ist Teil der Skills-Docs in `docs/skills/`._