From 085d8685a8483c83b94338f7679bfd973c16fc7f Mon Sep 17 00:00:00 2001
From: Jens Reinemann <reinemann@euris.de>
Date: Wed, 13 May 2026 22:29:09 +0200
Subject: [PATCH] docs(skills): align emulator and build docs with actual
 scripts

android-emulator SKILL.md:
- Added hot-reload and screenshot.ps1 to operations section
- Replaced broken 'exec-out > file' screenshot command with
  screenshot.ps1 reference and UTF-16 corruption warning
- Replaced blocking 'adb wait-for-device' with polling loop + timeout
  (consistent with android-dev.ps1 implementation)
- Added 30s PackageManager wait note after boot

android-build SKILL.md:
- Added screenshot.ps1 section with usage examples
- Documented PowerShell binary redirect UTF-16 bug as known issue

Motivation: docs diverged from scripts after GPU-mode, PM-wait,
screenshot.ps1 and hot-reload changes were added to the scripts.
---
 .github/skills/android-build/SKILL.md    | 15 ++++++++++++
 .github/skills/android-emulator/SKILL.md | 29 ++++++++++++++++++------
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/.github/skills/android-build/SKILL.md b/.github/skills/android-build/SKILL.md
index 5344776..b47d8b3 100644
--- a/.github/skills/android-build/SKILL.md
+++ b/.github/skills/android-build/SKILL.md
@@ -41,6 +41,21 @@ Verwende **immer** das `android-dev.ps1`-Skript statt roher Gradle-Aufrufe:
 & ".github/skills/android-build/android-dev.ps1" -Action hot-reload
 ```
 
+### Screenshot
+
+Screenshots sind ein eigenständiges Skript (nicht Teil von `android-dev.ps1`):
+
+```powershell
+# Screenshot mit PNG-Validierung
+& ".github/skills/android-build/screenshot.ps1"
+
+# Screenshot + sichtbare UI-Texte extrahieren
+& ".github/skills/android-build/screenshot.ps1" -UiDump
+```
+
+**Wichtig:** Niemals `adb exec-out screencap -p > file.png` in PowerShell verwenden –
+PowerShell konvertiert Binärdaten in UTF-16 und zerstört den PNG-Header.
+
 ### Direkter Gradle-Aufruf (Fallback)
 
 Falls das Skript nicht verfügbar ist:
diff --git a/.github/skills/android-emulator/SKILL.md b/.github/skills/android-emulator/SKILL.md
index 7da9976..5bc3b7b 100644
--- a/.github/skills/android-emulator/SKILL.md
+++ b/.github/skills/android-emulator/SKILL.md
@@ -26,12 +26,15 @@ Verwaltet den Android-Emulator für die Krisenvorrat-App. Das Standard-AVD simul
 ## Operationen via Skript (bevorzugt)
 
 ```powershell
-# Emulator starten (wartet auf Boot)
+# Emulator starten (wartet auf Boot + PackageManager)
 & ".github/skills/android-build/android-dev.ps1" -Action emulator-start
 
-# App bauen + auf Emulator installieren + starten
+# App bauen + auf Emulator installieren + starten (Kaltstart)
 & ".github/skills/android-build/android-dev.ps1" -Action deploy-emulator
 
+# Hot Reload: Build + Install + Relaunch auf laufendem Emulator (ohne Neustart)
+& ".github/skills/android-build/android-dev.ps1" -Action hot-reload
+
 # Nur installieren (ohne Build)
 & ".github/skills/android-build/android-dev.ps1" -Action install-emulator
 
@@ -43,6 +46,10 @@ Verwaltet den Android-Emulator für die Krisenvorrat-App. Das Standard-AVD simul
 
 # Logcat (gefiltert auf App)
 & ".github/skills/android-build/android-dev.ps1" -Action logcat
+
+# Screenshot (eigenes Skript mit PNG-Validierung)
+& ".github/skills/android-build/screenshot.ps1"
+& ".github/skills/android-build/screenshot.ps1" -UiDump  # mit Text-Extraktion
 ```
 
 ---
@@ -60,14 +67,17 @@ Start-Process "$env:ANDROID_HOME\emulator\emulator.exe" -ArgumentList "-avd S24U
 
 ```powershell
 $adb = "$env:ANDROID_HOME\platform-tools\adb.exe"
-& $adb wait-for-device
+$elapsed = 0
 do {
     Start-Sleep -Seconds 5
-    $boot = & $adb shell getprop sys.boot_completed 2>$null
-} while ($boot -ne "1")
+    $elapsed += 5
+    $boot = & $adb -e shell getprop sys.boot_completed 2>$null
+} while ($boot -ne "1" -and $elapsed -lt 300)
+# Danach 30s auf PackageManager warten!
+Start-Sleep -Seconds 30
 ```
 
-**Hinweis:** Der Boot dauert 30–90 Sekunden. `sys.boot_completed` gibt zunächst leeren String zurück.
+**Hinweis:** Der Boot dauert 30–90 Sekunden. Danach braucht der PackageManager weitere ~30s bevor `adb install` funktioniert. Das Skript behandelt beides automatisch.
 
 ### App installieren
 
@@ -98,9 +108,14 @@ do {
 ### Screenshot
 
 ```powershell
-& $adb exec-out screencap -p > tmp/screenshot.png
+# Robustes Skript (empfohlen – validiert PNG, umgeht PowerShell-Encoding-Bug)
+& ".github/skills/android-build/screenshot.ps1"
+& ".github/skills/android-build/screenshot.ps1" -UiDump  # zusätzlich sichtbare Texte ausgeben
 ```
 
+**Wichtig:** `adb exec-out screencap -p > file.png` funktioniert in PowerShell NICHT korrekt –
+PowerShell konvertiert Binärdaten in UTF-16 und korrumpiert den PNG-Header. Immer `screenshot.ps1` verwenden.
+
 ### Emulator beenden
 
 ```powershell