's'

README.md

@@ -17,6 +17,7 @@ It keeps only the parts that were actually used:
 - `run_redroid.py`
 - `bootstrap_redroid.py`
 - `verify_offline_bundle.py`
+- `tools/compat.py` (host / GPU / runtime checks)
 - `offline/README.md`
 - `offline/manifest.json`
 - `stuff/mindthegapps.py`
@@ -63,6 +64,28 @@ python verify_offline_bundle.py
 python -m pip install -r requirements.txt
 ```
 
+## Compatibility checks
+
+The project probes the **host** before critical steps (no separate manual checklist required):
+
+| Step | What it checks | Opt-out |
+|------|----------------|---------|
+| `redroid.py` | Container runtime (`docker`/`podman`) responds; OS is plausible for redroid | `--no-compat-check` |
+| `run_redroid.py` | Same + Linux **`/dev/dri`** for GPU; **`binder_linux`** module hint on Linux | `--no-compat-check` |
+
+**GPU mode (`run_redroid.py`):**
+
+- **`--gpu-mode auto` (default):** uses **`host`** when DRI devices exist and automatically adds `docker run --device …` for each `/dev/dri/card*` / `renderD*` node; otherwise **`guest`** (software GLES).
+- **`--gpu-mode host`:** pass-through when DRI exists; otherwise **falls back to `guest`** with a warning.
+- **`--gpu-mode guest`:** force software rendering (common black-screen case on headless servers).
+
+Quick probe only:
+
+```bash
+python tools/compat.py
+python tools/compat.py -c podman --gpu-mode auto
+```
+
 ## Build the 5570 image
 
 ```bash
@@ -112,6 +135,33 @@ If you still see `unauthorized` after an upgrade, stop the container, remove per
 rm -rf ~/data-redroid13/misc/adb
 ```
 
+## Black screen or flickering
+
+With **`--gpu-mode guest`** (or **`auto`** when no `/dev/dri` exists), the display uses **software GLES** (SwiftShader). On many **headless servers**, SurfaceFlinger may show a **black screen**, **flicker**, or very low FPS. That is a **display stack** issue, not ADB. The default **`auto`** mode uses **host** GPU when DRI nodes are visible and injects **`--device`** flags automatically.
+
+**What to try**
+
+1. **GPU on the host:** ensure **`--gpu-mode auto`** (default) so DRI is detected, or set **`--gpu-mode host`** explicitly. If you must pass devices manually (unusual when `auto` works), for example:
+   ```bash
+   docker run ... --device /dev/dri ...
+   ```
+   The exact device path varies (Intel/AMD/NVIDIA, `nvidia-docker`, etc.); see [redroid-doc](https://github.com/remote-android/redroid-doc) GPU notes.
+
+2. **Stay on software rendering** but tune the virtual panel (sometimes reduces glitches):
+   ```bash
+   python run_redroid.py ... --adb-insecure \
+     --extra-prop androidboot.redroid_width=720 \
+     --extra-prop androidboot.redroid_height=1280 \
+     --extra-prop androidboot.redroid_fps=15
+   ```
+
+3. **First boot / SetupWizard** can sit on a dark screen for a while. Run **`bootstrap_redroid.py`** once `adb` shows `device` so provisioning and wizard are skipped as intended.
+
+4. **Debug with logcat** (on the host, after `adb connect`):
+   ```bash
+   adb -s 127.0.0.1:5570 logcat -d | grep -iE 'SurfaceFlinger|EGL|GLES|redroid'
+   ```
+
 ## Apply the 5570 hardening
 
 ```bash