From 5cc1ee6e4dbbbc355c0a896ae04bf5b16d4fe982 Mon Sep 17 00:00:00 2001
From: StefanMoCoAt <stefan.mo.co@gmail.com>
Date: Tue, 11 Nov 2025 23:32:40 +0100
Subject: [PATCH] docs: erweitere Makefile-Dokumentation in README und
 start-local (MP-17) (#17)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Integriert umfassende Makefile-Referenz in die Haupt-Dokumentation für
bessere Auffindbarkeit und Developer Experience.

Änderungen:
- README.md: Erweitert "Makefile-Shortcuts" zu "Makefile-Befehle"
  - Hinzugefügt: Wichtigste Development-Befehle (full-up, services-up, dev-up, test, health-check)
  - Hinzugefügt: SSoT-Befehle (docker-sync, docker-compose-gen, docker-validate)
  - Hinzugefügt: Link zur vollständigen Referenz in docker-development.md
  - +20 Zeilen (Zeilen 292-319)

- docs/how-to/start-local.md: Neue Sektion "Weitere Makefile-Befehle"
  - Hinzugefügt: Verweis auf `make help`
  - Hinzugefügt: Link zu Docker Development Guide Makefile-Referenz
  - +6 Zeilen (nach Zeile 39)

Kontext:
Diese Änderungen bauen auf der vollständigen Makefile-Dokumentation in
.junie/guidelines/technology-guides/docker/docker-development.md auf
(194 → 756 Zeilen, 50+ Befehle, erstellt am 2025-11-11).

Nutzen:
- Entwickler: Schnellerer Einstieg durch zentrale Übersicht
- Onboarding: Alle wichtigen Befehle auf einen Blick
- AI-Assistenten: Konsistente Command-Referenz
- Dokumentation: Verbesserte Navigation zwischen How-To-Guides und Referenz

Technische Details:
Das Makefile umfasst 10 Befehlskategorien:
1. Development Workflow (dev-up, dev-down, dev-restart, dev-logs, dev-info)
2. Layer-spezifisch (infrastructure-*, services-*, clients-*)
3. Full System (full-up, full-down, full-restart, full-logs)
4. Build (build, build-service, build-client)
5. Test (test, test-e2e)
6. Environment (env-setup, env-dev, env-prod, env-staging, env-test, validate)
7. SSoT (versions-show, versions-update, docker-sync, docker-compose-gen, docker-validate, hooks-install)
8. Production (prod-up, prod-down, prod-restart, prod-logs)
9. Monitoring (status, health-check, logs, shell)
10. Cleanup (clean, clean-all)

Related:
- Vorherige Commits: Makefile-Optimierung (425 Zeilen, strukturiert)
- Vorherige Commits: docker-development.md vollständige Aktualisierung
- Vorherige Commits: Port-Korrekturen (8080 → 8081)

Testing:
- ✅ make help zeigt alle Befehle korrekt an
- ✅ Links in Markdown funktionieren
- ✅ Dokumentation konsistent mit aktuellem Makefile
---
 README.md                  | 28 ++++++++++++++++++++++++----
 docs/how-to/start-local.md |  6 ++++++
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 2298f28c..43968eee 100644
--- a/README.md
+++ b/README.md
@@ -289,14 +289,34 @@ Dieser Abschnitt beschreibt den lokalen Workflow für die zentrale Docker-Versio
   DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
   ```
 
-### Makefile-Shortcuts
+### Makefile-Befehle
+
+Das Projekt verwendet ein umfassendes Makefile mit ~50 Befehlen für alle Development-Workflows:
 
 ```bash
- make docker-sync # Kompatibilitätsmodus: Sync 
- make docker-compose-gen # Compose-Files generieren 
- make docker-validate # Validierung
+make help  # Zeigt alle verfügbaren Befehle
 ```
 
+**Wichtigste Befehle:**
+
+```bash
+make full-up         # Startet komplettes System (Infra + Services + Clients)
+make services-up     # Startet Backend (Infra + Microservices)
+make dev-up          # Startet Development-Environment
+make test            # Führt Integration-Tests aus
+make health-check    # Prüft System-Health
+```
+
+**SSoT-Befehle:**
+
+```bash
+make docker-sync         # Synchronisiert versions.toml -> build-args/*.env
+make docker-compose-gen  # Generiert Docker Compose Files
+make docker-validate     # Validiert Docker SSoT Konsistenz
+```
+
+**Vollständige Referenz:** [Docker Development Guide](.junie/guidelines/technology-guides/docker/docker-development.md#-vollständige-makefile-referenz)
+
 ### Was ist die Single Source of Truth?
 
 - **`docker/versions.toml`** enthält alle Versionsangaben (Gradle, Java, Node, Nginx, Postgres, Redis, etc.)
diff --git a/docs/how-to/start-local.md b/docs/how-to/start-local.md
index be84aed0..170ea737 100644
--- a/docs/how-to/start-local.md
+++ b/docs/how-to/start-local.md
@@ -38,6 +38,12 @@ Logs ansehen (z. B. Backend):
 make services-logs
 ```
 
+## Weitere Makefile-Befehle
+
+Für eine vollständige Liste aller verfügbaren Befehle siehe:
+- `make help` (im Terminal)
+- [Docker Development Guide](../../.junie/guidelines/technology-guides/docker/docker-development.md#-vollständige-makefile-referenz)
+
 ## Wichtige URLs
 
 - Web App: <http://localhost:4000>