From 7b4a9c1fe3f2d7be1b11260bbfd0cf8619729918 Mon Sep 17 00:00:00 2001
From: dev <dev@local>
Date: Sat, 28 Feb 2026 15:40:00 +0000
Subject: [PATCH] docs: add runtime configuration reference

---
 docs/runtime-config.md | 87 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/runtime-config.md

diff --git a/docs/runtime-config.md b/docs/runtime-config.md
new file mode 100644
index 0000000..33aa2f3
--- /dev/null
+++ b/docs/runtime-config.md
@@ -0,0 +1,87 @@
+# Runtime and Configuration
+
+## Backend Resolution
+
+CLI option:
+
+```text
+scanslicer --backend {auto,wayland,x11}
+```
+
+Resolution order when `--backend auto`:
+
+1. `QT_QPA_PLATFORM` explicit hint (`wayland`, `xcb`, `x11`)
+2. `XDG_SESSION_TYPE` (`wayland` or `x11`)
+3. Wayland socket presence (`XDG_RUNTIME_DIR` + `WAYLAND_DISPLAY`)
+4. `DISPLAY` presence (X11)
+5. fallback to Wayland
+
+## Backend Validation
+
+- Wayland requires:
+  - `XDG_RUNTIME_DIR`
+  - `WAYLAND_DISPLAY`
+  - existing socket at `$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY`
+- X11 requires:
+  - `DISPLAY`
+
+On startup failure, ScanSlicer prints backend-specific hints to stderr.
+
+## Qt Environment Adjustments
+
+- For Wayland mode:
+  - sets `QT_QPA_PLATFORM=wayland`
+  - unsets `DISPLAY` to avoid accidental XWayland routing
+- For X11 mode:
+  - sets `QT_QPA_PLATFORM=xcb`
+- In Flatpak/Snap:
+  - defaults `QT_QPA_PLATFORMTHEME=xdgdesktopportal`
+- In AppImage:
+  - defaults `QT_QPA_PLATFORMTHEME=gtk3`
+  - sets `QT_NO_XDG_DESKTOP_PORTAL=1`
+- In container (`/.dockerenv`):
+  - defaults `QT_QPA_PLATFORMTHEME=gtk3`
+
+## Persistence Paths
+
+### Defaults and presets
+
+- Defaults JSON:
+  - host: `~/.config/scanslicer/defaults.json`
+  - container: `/work/.scanslicer/defaults.json`
+  - override: `SCANSLICER_DEFAULTS_PATH`
+- Presets JSON:
+  - host: `~/.config/scanslicer/presets.json`
+  - container: `/work/.scanslicer/presets.json`
+  - override: `SCANSLICER_PRESETS_PATH`
+
+### Auto-tune feedback
+
+- host: `~/.config/scanslicer/autotune-feedback.json`
+- container: `/work/.scanslicer/autotune-feedback.json`
+- override: `SCANSLICER_FEEDBACK_PATH`
+
+### Status log
+
+- host: `~/.config/scanslicer/status.log`
+- container: `/work/.scanslicer/status.log`
+- override: `SCANSLICER_STATUS_LOG_PATH`
+
+Legacy override names are still accepted for backward compatibility.
+
+Status log behavior:
+
+- new app launch truncates and starts a fresh session log
+- batched flushing by time and queue size
+
+## Container Runtime Notes
+
+`docker-compose.yml` expects desktop/session wiring:
+
+- `UID`, `GID` for correct file ownership
+- `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`
+- mounted Wayland socket and DBus session bus
+- host home mounted at `/host-home`
+- project mounted at `/work`
+
+See `.env.example` for a baseline.