Plan implementation iteration 1: DSH-1 and configuration

D38: app-specific command-line options in the platform. D39: WebEngine
initialisation in main.cpp, persistent profile, tab "HA Dashboard".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/DESIGN.md

@@ -99,10 +99,10 @@ Two overlay kinds in the platform (D25):
 
 | Overlay | Kind | Visibility | MVP |
 |---|---|---|---|
-| Main tab (UI-1, later NOT-7, do-not-disturb) | dashboard tab | always there; SteamVR shows/hides it | ✓ |
+| Main tab "Frame Assistant" (UI-1, later NOT-7, do-not-disturb) | dashboard tab | always there; SteamVR shows/hides it | ✓ |
 | Notifications | world overlay | the app (notification manager) shows/hides it | ✓ |
 | Status tab (SRV-6) | dashboard tab | exists only while cards exist (D9) | ✗ |
-| HA dashboard (DSH-1, web UI test) | dashboard tab | always there | ✓ |
+| "HA Dashboard" (DSH-1, web UI test) | dashboard tab | always there | ✓ |
 
 - **World overlays (MVP):** a new overlay kind next to the dashboard tab (CLAUDE.md, "Planned
   extension"). The surface gets a kind and a placement; renders only while visible (NFR-3).
@@ -444,3 +444,5 @@ Collected 2026-10-05 for the notification design.
 | D35 | 2026-10-05 | Ship libmosquitto like OpenVR: pkg-config at build time, copied to `lib/` by a CMake option for package presets, excluded from the Qt bundler, licence shipped; `package-release.sh` checks symbol versions against the Frame | Not on the Frame; keeps the platform MQTT-free; a Debian update that breaks compatibility shows up when packaging |
 | D36 | 2026-10-05 | NFR-3 measured as own cost (CPU idle, frames while hidden, GPU per frame) plus an A/B comparison of the game's compositor statistics; manual in the MVP, a `--vr-stats` mode later | Measurable acceptance for NFR-3 without extra code in the MVP |
 | D37 | 2026-10-05 | The MVP is implemented in four iterations: 1 DSH-1 + configuration, 2 MQTT/HA device/UI-1, 3 sensors, 4 notifications | Small iterations (working rules); DSH-1 first because the user wants to see it early and it doesn't depend on MQTT |
+| D38 | 2026-10-05 | App-specific command-line options: the platform's base constructor takes an optional list of extra options, parses them with its own and exposes their values | The command line is parsed in the base constructor, before the derived app can contribute (`--config`); backward compatible, `--help` stays complete |
+| D39 | 2026-10-05 | DSH-1: `QtWebEngineQuick::initialize()` in `main.cpp` (no platform change); a named, persistent WebEngine profile under `~/.local/share/frameassistant/`; tab name "HA Dashboard" | WebEngine must be initialised before the `QGuiApplication`; the HA login must survive restarts |

docs/PROGRESS.md

@@ -5,9 +5,9 @@ CLAUDE.md ("Working rules").
 
 ## Current state
 
-- **Iteration 1, phase 2 (planning and design).** Phase 1 is approved (D13);
-  [REQUIREMENTS.md](REQUIREMENTS.md) is the baseline. High-level architecture done
-  ([DESIGN.md](DESIGN.md)); MVP details next.
+- **Implementation iteration 1 (DSH-1 and configuration), phase 3 (implementation).**
+  Requirements (D13) and design ([DESIGN.md](DESIGN.md)) are approved; the plan below was
+  approved on 2026-10-05.
 
 ## Next steps
 
@@ -21,8 +21,46 @@ Requirements and design cover the whole MVP; it is **implemented in four small i
 | 3 | OpenVR wrappers and the 13 sensor entities | `--desktop` with optional SteamVR (D22) | sensor values in HA on the Frame |
 | 4 | notification manager, `notify` entity, world overlay | world overlay, premultiplied flag (D25) | notification from HA in VR, also in a game |
 
-Next: the detailed plan for iteration 1 (files, classes, tests, order) for the user's
-approval; that ends phase 2 for iteration 1.
+### Plan for implementation iteration 1: DSH-1 and configuration
+
+Goal: a second dashboard tab **"HA Dashboard"** shows HA's web UI at the URL from the
+configuration; what works out of the box is tested and documented. The main tab stays
+"Frame Assistant".
+
+Platform (`vrdashboard_core`):
+1. Start-up hook `prepare()` (D21).
+2. App-specific command-line options (D38): the base constructor takes an optional list of
+   extra `QCommandLineOption`s, adds them to parsing and `--help`, and exposes their values.
+
+App:
+3. `QtWebEngineQuick::initialize()` in `main.cpp` before the app object (D39); no platform
+   change.
+4. Configuration (`src/config/`): immutable value plus `load(path, &error)`, complete per D34;
+   path from `--config`, else `$XDG_CONFIG_HOME` or `~/.config/frameassistant/config.json`;
+   loaded in `Dashboard::prepare()` (overlay and desktop modes).
+5. HA web UI (`src/ha/HaWebUi`, D18): holds the URL (injected), exposed to QML as a singleton
+   owned by `Dashboard`; a named, persistent WebEngine profile under
+   `~/.local/share/frameassistant/` so the HA login survives restarts (D39).
+6. New surface `dashboard` ("HA Dashboard"), QML root `HaDashboard.qml` with a `WebEngineView`;
+   without a URL it shows a hint.
+7. Build: `find_package(Qt6 … WebEngineQuick)`; `qt6-webengine-dev` (native and `:arm64`) in
+   the containers; a new static library for app logic (configuration, HaWebUi) that tests link.
+
+Tests (D30):
+8. `tst_config`: valid file, missing required fields, invalid JSON, wrong types, defaults,
+   derived and explicit `ha_unique_id`, unknown keys, `--config`.
+9. Platform: `tst_surfaces` extended for `prepare()` (success/abort) and extra options.
+10. Manual, results documented: host `--desktop`; Frame desktop mode over RDP; Frame in VR with
+    Vulkan and OpenGL: page loads, laser click, scrolling, SteamVR keyboard in the page's input
+    fields, login kept after restart; CPU/GPU while the tab is open.
+11. `clang-format` clean, `ctest` green; `container-test.sh` only if Vulkan code is touched.
+
+Docs:
+12. README (configuration file, `--config`, new tab), ARCHITECTURE.md and CLAUDE.md (new hook,
+    app options), THIRD_PARTY_NOTICES (Qt WebEngine from the system), STEAM-FRAME.md (results),
+    PROGRESS.md.
+
+Known limitation: the bundled-Qt package does not support WebEngine in this iteration.
 
 ## Log
 
@@ -39,6 +77,8 @@ approval; that ends phase 2 for iteration 1.
   present (relevant for Q2/Q3).
 - libmosquitto ABI check: Debian's 2.0.21 needs at most `OPENSSL_3.0.0`/`GLIBC_2.34`; the
   Frame has OpenSSL 3.2.1 and glibc 2.39. No libcjson dependency. D14 holds.
+- Plan for implementation iteration 1 approved; phase 3 started.
+- Plan for implementation iteration 1 written; new tab "HA Dashboard" (D38, D39).
 - MVP implemented in four iterations; DSH-1 first, at the user's wish (D37).
 - NFR-3 measurement method, manual in the MVP (D36). MVP details done.
 - Shipping libmosquitto (D35).