diff --git a/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md b/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md
new file mode 100644
index 00000000..d351a53f
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md
@@ -0,0 +1,2694 @@
+# Einrichtungsassistent, Ausbaustufe 1 — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ein unkonfiguriertes Operatorprofil startet in einem Einrichtungsassistenten, der Persönliches, Anmeldung, Standort und Bänder abfragt und `preferences.xml` schreibt, bevor die Laufzeit gebaut wird.
+
+**Architecture:** Der Assistent läuft vor dem `ChatController` auf einem eigenen `ChatPreferences`-Objekt und schreibt die Datei; `startRuntime` liest sie danach wie jede gespeicherte Einstellung. Er ändert keine laufende Sitzung und berührt `SettingsDraft` nicht. Aus dem Menü wird die Laufzeit erst abgebaut, dann das selbe Profil mit dem Assistenten neu gestartet.
+
+**Tech Stack:** Java 21 (`core`), Kotlin 2.2 und Compose Multiplatform 1.8 (`app-desktop`), JUnit 5, Gradle-Wrapper.
+
+**Spec:** `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md` — dieser Plan setzt **nur Ausbaustufe 1** um. Die Stufen 2 (Antenne, Logprogramm, Rotor, AirScout) und 3 („von Profil X übernehmen") bekommen eigene Pläne, sobald Stufe 1 steht; ihre Schritte hängen an den Formen, die hier entstehen.
+
+## Global Constraints
+
+- Gradle, nicht Maven. Java 21. Bau und Tests über `./gradlew`.
+- Quelltextkommentare und Javadoc ausschließlich Englisch. Kommunikation und Handbuch-Deutsch in neuer Rechtschreibung (`muss`, `dass`).
+- `core` erzeugt keinen Anzeigetext und kennt kein Toolkit. Die Erkennung liegt in `core`, alles Sichtbare in `app-desktop`.
+- Oberflächentexte stehen in `app-desktop/src/main/i18n/strings_en.properties` (Basis) und `strings_de.properties`. Beide Dateien bekommen jeden neuen Schlüssel. Ein Schlüssel nur in der deutschen Datei bricht den Bau.
+- Kein Apostroph in den neuen Texten: parametrisierte Texte laufen durch `MessageFormat`.
+- Bandbezeichnungen (`144 MHz`) und Kategorienamen sind Funkerkürzel und werden nicht übersetzt.
+- Rufzeichen und Locator werden gespeichert, wie sie getippt wurden, nur ohne Leerraum am Rand. Keine neue Normalisierung.
+- Nie blockierend auf dem AWT-Ereignisfaden warten. Das Fenster ist ein modaler `ComposeDialog`, geöffnet über `openOnEventThread`, wie `OperatorProfilePickerWindow`.
+- Unverändert bleiben: das Format von `preferences.xml`, das Einstellungsfenster mit seinen zwölf Reitern, `SettingsDraft.apply`, `OperatorProfileManagementService`, `praktiKSTpreferences.xml`.
+- Unkonfiguriert heißt: Rufzeichen leer, oder Rufzeichen `DO5AMF` mit Passwort `changeMe`.
+- Pflichtangaben für „Fertig" und „Speichern": Anzeigename, Rufzeichen, Passwort, Locator, mindestens ein Band, Chatkategorie.
+- Kein Commit, kein Push ohne ausdrücklichen Auftrag des Nutzers (`AGENTS.md`). Die Commit-Schritte unten gelten nur, wenn der Auftrag zur Ausführung das Committen einschließt; sonst bleiben die Änderungen im Arbeitsbaum.
+- Ein Testfehler bricht den Bau, PMD und SpotBugs nicht. Ergebnis aus der Test-XML unter `*/build/test-results/` lesen, nicht aus dem Rückgabewert.
+
+## Review Focus
+
+1. **Rufzeichen mit Zusatz oder in Kleinschrift** (`DL0TEST/P`, `DO5AMF-2`, `do5amf`): wird angenommen und unverändert gespeichert. Test in Task 2 (`callsignsWithSuffixAndLowerCaseAreAccepted`) und Task 3 (`aCallsignIsStoredAsTyped`).
+2. **Gespeicherte Chatkategorie außerhalb 1–3** (etwa 7) bei „unverändert lassen": bleibt 7, der Assistent schlägt nichts darüber. Test in Task 3 (`aKeptCategoryOutsideTheSuggestionsSurvives`).
+3. **Die Datei lässt sich nicht schreiben**: der Assistent bleibt offen und meldet es, statt sich mit „gespeichert" zu schließen. Test in Task 3 (`aFailedWriteIsReported`) und Task 5 (`aFailedSaveKeepsTheWizardOpen`).
+4. **Die Profildatei ist unlesbar**: der Assistent erscheint nicht und überschreibt nichts; der Start geht weiter wie heute. Test in Task 5 (`anUnreadableFileNeverOpensTheWizard`).
+5. **Fenster über das X geschlossen**: zählt als „Später", schreibt nichts. Test in Task 5 (`closingTheWindowCountsAsLater`).
+
+---
+
+## Dateien
+
+| Datei | Aufgabe |
+|---|---|
+| `core/src/main/java/kst4contest/controller/LoginConfiguration.java` (neu) | Erkennung „unkonfiguriert" und Vorlagen-Anmeldedaten |
+| `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java` (neu) | deren Tests, auch gegen die mitgelieferte Vorlage |
+| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (neu) | Zustand, Ablauf, Prüfregeln, Schreiben der Antworten |
+| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt` (neu) | die Seiten als Composables |
+| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt` (neu) | modaler Dialog, Ergebnis, Starter |
+| `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/*Test.kt` (neu) | Tests dazu |
+| `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` | neue Texte |
+| `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` | Aufruf im Start, Verbinden danach, Menüaktion |
+| `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java` | Wunsch „Assistent zeigen", Neustart des selben Profils |
+| `app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java`, `.../compose/MainMenuBar.kt`, `.../compose/MainMenuModel.kt` | Menüeintrag |
+| `docs/PROJECT_CONTEXT.md`, `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` | Dokumentation |
+
+---
+
+### Task 1: Erkennung eines unkonfigurierten Profils
+
+**Files:**
+- Create: `core/src/main/java/kst4contest/controller/LoginConfiguration.java`
+- Test: `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java`
+
+**Interfaces:**
+- Consumes: `ChatPreferences.getStn_loginCallSign()`, `getStn_loginPassword()`, `ChatPreferences.PREFERENCE_RESOURCE`, Konstruktor `ChatPreferences(Path)`.
+- Produces:
+ - `public static final String LoginConfiguration.TEMPLATE_CALLSIGN` (`"DO5AMF"`)
+ - `public static final String LoginConfiguration.TEMPLATE_PASSWORD` (`"changeMe"`)
+ - `public static boolean LoginConfiguration.carriesTemplateCredentials(ChatPreferences)`
+ - `public static boolean LoginConfiguration.isUnconfigured(ChatPreferences)`
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package kst4contest.controller;
+
+import kst4contest.model.ChatPreferences;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * When a profile counts as not set up yet. The setup wizard appears on exactly this
+ * condition, so a wrong answer either nags a working station or leaves a newcomer alone
+ * with the template's callsign.
+ */
+class LoginConfigurationTest {
+
+ @TempDir
+ Path temporaryDirectory;
+
+ private ChatPreferences preferences(String callsign, String password) {
+ ChatPreferences preferences = new ChatPreferences(temporaryDirectory.resolve("unused.xml"));
+ preferences.setStn_loginCallSign(callsign);
+ preferences.setStn_loginPassword(password);
+ return preferences;
+ }
+
+ @Test
+ void anEmptyCallsignIsUnconfigured() {
+ assertTrue(LoginConfiguration.isUnconfigured(preferences("", "secret")));
+ assertTrue(LoginConfiguration.isUnconfigured(preferences(" ", "secret")));
+ }
+
+ @Test
+ void theTemplateCredentialsAreUnconfigured() {
+ ChatPreferences template = preferences("DO5AMF", "changeMe");
+
+ assertTrue(LoginConfiguration.carriesTemplateCredentials(template));
+ assertTrue(LoginConfiguration.isUnconfigured(template));
+ }
+
+ @Test
+ void theTemplateCallsignWithItsOwnPasswordIsConfigured() {
+ // The callsign belongs to a real operator; only the pair marks an untouched template.
+ ChatPreferences owner = preferences("DO5AMF", "a-real-password");
+
+ assertFalse(LoginConfiguration.carriesTemplateCredentials(owner));
+ assertFalse(LoginConfiguration.isUnconfigured(owner));
+ }
+
+ @Test
+ void aRealLoginIsConfigured() {
+ assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST", "secret")));
+ assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST/P", "")));
+ }
+
+ @Test
+ void theConstantsMatchTheBundledTemplate() throws IOException {
+ Path templateCopy = temporaryDirectory.resolve("template.xml");
+ try (InputStream template = ChatPreferences.class
+ .getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE)) {
+ assertNotNull(template, "bundled resource " + ChatPreferences.PREFERENCE_RESOURCE);
+ Files.copy(template, templateCopy, StandardCopyOption.REPLACE_EXISTING);
+ }
+
+ ChatPreferences fromTemplate = new ChatPreferences(templateCopy);
+ assertTrue(fromTemplate.readPreferencesFromXmlFile());
+
+ assertTrue(LoginConfiguration.carriesTemplateCredentials(fromTemplate),
+ "the template's credentials changed; a fresh installation would no longer "
+ + "be recognised as unconfigured");
+ }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'`
+Expected: Kompilierfehler, `cannot find symbol ... LoginConfiguration`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```java
+package kst4contest.controller;
+
+import kst4contest.model.ChatPreferences;
+
+/**
+ * Tells whether a profile has login credentials an operator entered.
+ *
+ *
Two states count as unconfigured. An empty callsign is what every created or duplicated
+ * profile starts with, because {@link OperatorProfileManagementService} clears the
+ * credentials on purpose. The bundled template's credentials are what the root profile of a
+ * fresh installation carries. Neither can log in as the operator, so neither needs a flag of
+ * its own in {@code preferences.xml}.
+ */
+public final class LoginConfiguration {
+
+ /** Callsign shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */
+ public static final String TEMPLATE_CALLSIGN = "DO5AMF";
+
+ /** Password shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */
+ public static final String TEMPLATE_PASSWORD = "changeMe";
+
+ private LoginConfiguration() {
+ // Utility class.
+ }
+
+ /**
+ * Whether the preferences still hold the bundled template's credentials.
+ *
+ * Only the pair counts. The callsign alone belongs to a real operator.
+ *
+ * @param preferences preferences of the profile to judge
+ * @return true for an untouched template
+ */
+ public static boolean carriesTemplateCredentials(final ChatPreferences preferences) {
+ return TEMPLATE_CALLSIGN.equalsIgnoreCase(trimmed(preferences.getStn_loginCallSign()))
+ && TEMPLATE_PASSWORD.equals(preferences.getStn_loginPassword());
+ }
+
+ /**
+ * Whether the profile has no login an operator entered.
+ *
+ * @param preferences preferences of the profile to judge
+ * @return true when the callsign is empty or the template's credentials are still there
+ */
+ public static boolean isUnconfigured(final ChatPreferences preferences) {
+ return trimmed(preferences.getStn_loginCallSign()).isEmpty()
+ || carriesTemplateCredentials(preferences);
+ }
+
+ private static String trimmed(final String value) {
+ return value == null ? "" : value.trim();
+ }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'`
+Expected: 5 Tests, 0 Fehler in `core/build/test-results/test/TEST-kst4contest.controller.LoginConfigurationTest.xml`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add core/src/main/java/kst4contest/controller/LoginConfiguration.java core/src/test/java/kst4contest/controller/LoginConfigurationTest.java
+git commit -m "Detect operator profiles without entered login credentials"
+```
+
+---
+
+### Task 2: Zustand und Ablauf des Assistenten
+
+**Files:**
+- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt`
+- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt`
+
+**Interfaces:**
+- Consumes: `LoginConfiguration.isUnconfigured`, `LoginConfiguration.carriesTemplateCredentials` (Task 1); Getter von `ChatPreferences`.
+- Produces (alle in Paket `kst4contest.view.compose.wizard`):
+ - `enum class WizardSource { NEW, KEEP }`
+ - `enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY }`
+ - `enum class WizardBand(val label: String, val megahertz: Int)` mit `B50, B70, B144, B432, B1240, B2300, B3400, B5600, B10G`
+ - `class SetupWizardState(prefs: ChatPreferences)` mit
+ - `val loginSources: List`, `val stationSources: List`, `val hasEntryPage: Boolean`
+ - `val loginSource: WizardSource?`, `val stationSource: WizardSource?`, `fun chooseLoginSource(WizardSource)`, `fun chooseStationSource(WizardSource)`
+ - `val storedCallsign: String`, `val storedLocator: String`
+ - `var language: String`, `var name: String`, `var callsign: String`, `var password: String`, `var locator: String`
+ - `val bands: Set`, `fun setBand(WizardBand, Boolean)`
+ - `val category: Int?`, `fun chooseCategory(Int)`, `val suggestedCategory: Int?`
+ - `val secondChat: Boolean`, `fun chooseSecondChat(Boolean)`, `var secondCategory: Int?`, `val secondCategoryOptions: List`
+ - `val page: WizardPage`, `val pages: List`
+ - `val canGoNext: Boolean`, `val canGoBack: Boolean`, `val canFinish: Boolean`, `val mandatoryComplete: Boolean`
+ - `val callsignRefused: Boolean`, `val locatorRefused: Boolean`
+ - `fun next()`, `fun back()`, `fun finish()`, `fun edit(WizardPage)`
+ - `val turnsOffSecondChat: Boolean`, `val leavesIntegrationsUntouched: Boolean`
+ - `companion`: `val CATEGORY_NUMBERS: List`, `fun isPlausibleCallsign(String): Boolean`, `fun isLocator(String): Boolean`, `fun suggestCategory(Set): Int?`
+
+- [ ] **Step 1: Write the failing test**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import kst4contest.model.ChatCategory
+import kst4contest.model.ChatPreferences
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertNull
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+import java.nio.file.Path
+
+/**
+ * The wizard's rules without a window: which pages appear, what they start with, and when
+ * the operator may go on. Nothing here reads or writes a file.
+ */
+class SetupWizardStateTest {
+
+ /** Preferences that never touch a file: the path is only read by read/write calls. */
+ private fun prefs(configure: ChatPreferences.() -> Unit = {}): ChatPreferences =
+ ChatPreferences(Path.of("setup-wizard-state-test-unused.xml")).apply(configure)
+
+ private fun freshInstallation() = prefs {
+ setStn_loginCallSign("DO5AMF")
+ setStn_loginPassword("changeMe")
+ setStn_loginNameMainCat("KST4Contest1263")
+ setStn_loginLocatorMainCat("JO54ME")
+ setStn_bandActive144(true)
+ setLoginChatCategoryMain(ChatCategory(2))
+ setLoginToSecondChatEnabled(true)
+ setLoginChatCategorySecond(ChatCategory(3))
+ }
+
+ private fun duplicatedProfile() = prefs {
+ setStn_loginCallSign("")
+ setStn_loginPassword("")
+ setStn_loginNameMainCat("Other Operator")
+ setStn_loginLocatorMainCat("JO50AA")
+ setStn_bandActive144(true)
+ setStn_bandActive432(true)
+ setLoginChatCategoryMain(ChatCategory(2))
+ setLoginToSecondChatEnabled(false)
+ }
+
+ private fun configuredProfile() = duplicatedProfile().apply {
+ setStn_loginCallSign("DL0TEST")
+ setStn_loginPassword("secret")
+ setStn_loginNameMainCat("Philipp")
+ }
+
+ /** Fills every mandatory answer of a first installation, leaving the wizard on SITE. */
+ private fun SetupWizardState.fillFirstInstallation() {
+ name = "Philipp"
+ next()
+ callsign = "DL0TEST"
+ password = "secret"
+ next()
+ locator = "JO50AA"
+ setBand(WizardBand.B144, true)
+ }
+
+ @Test
+ fun aFreshInstallationHasNoEntryPageAndStartsEmpty() {
+ val state = SetupWizardState(freshInstallation())
+
+ assertFalse(state.hasEntryPage)
+ assertEquals(WizardPage.PERSONAL, state.page)
+ assertEquals(
+ listOf(WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SITE, WizardPage.SUMMARY),
+ state.pages,
+ )
+ assertEquals("", state.name, "the template's name is nobody's name")
+ assertEquals("", state.callsign)
+ assertEquals("", state.locator)
+ assertTrue(state.bands.isEmpty())
+ assertNull(state.category)
+ assertFalse(state.secondChat)
+ }
+
+ @Test
+ fun aDuplicatedProfileIsAskedOnlyAboutTheStation() {
+ val state = SetupWizardState(duplicatedProfile())
+
+ assertEquals(listOf(WizardSource.NEW), state.loginSources)
+ assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources)
+ assertTrue(state.hasEntryPage)
+ assertEquals(WizardPage.ENTRY, state.page)
+ assertEquals(WizardSource.NEW, state.loginSource, "a single option is chosen already")
+ assertNull(state.stationSource, "nothing is preselected where there is a choice")
+ assertFalse(state.canGoNext)
+ }
+
+ @Test
+ fun aConfiguredProfileMayKeepBoth() {
+ val state = SetupWizardState(configuredProfile())
+
+ assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources)
+ assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources)
+ assertEquals("Philipp", state.name, "a configured profile keeps its operator's name")
+ }
+
+ @Test
+ fun keepingTheStationSkipsItsStepAndCarriesTheStoredValues() {
+ val state = SetupWizardState(duplicatedProfile())
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+
+ assertEquals(
+ listOf(WizardPage.ENTRY, WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SUMMARY),
+ state.pages,
+ )
+ assertEquals("JO50AA", state.locator)
+ assertEquals(setOf(WizardBand.B144, WizardBand.B432), state.bands)
+ assertEquals(2, state.category)
+ }
+
+ @Test
+ fun aNewStationStartsEmptyEvenOnAProfileThatHasOne() {
+ val state = SetupWizardState(duplicatedProfile())
+ state.chooseStationSource(WizardSource.NEW)
+ state.next()
+
+ assertEquals("", state.locator)
+ assertTrue(state.bands.isEmpty())
+ assertNull(state.category)
+ assertTrue(state.pages.contains(WizardPage.SITE))
+ }
+
+ @Test
+ fun goingBackToTheEntryPageAndOnAgainKeepsWhatWasTyped() {
+ val state = SetupWizardState(duplicatedProfile())
+ state.chooseStationSource(WizardSource.NEW)
+ state.next()
+ state.name = "Philipp"
+ state.back()
+ state.next()
+
+ assertEquals("Philipp", state.name)
+
+ state.next()
+ state.callsign = "DL0TEST"
+ state.back()
+ state.back()
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+
+ assertEquals("JO50AA", state.locator, "a changed source loads its own values")
+ state.next()
+ assertEquals("DL0TEST", state.callsign, "the login source did not change")
+ }
+
+ @Test
+ fun callsignsWithSuffixAndLowerCaseAreAccepted() {
+ listOf("DL0TEST", "DL0TEST/P", "DO5AMF-2", "do5amf", " DL0TEST ").forEach {
+ assertTrue(SetupWizardState.isPlausibleCallsign(it), "'$it' must be accepted")
+ }
+ listOf("", "DL", "ABC", "123", "DL0 TEST", "DL0TEST|X", "DL0-TEST-2", "DL0TEST/").forEach {
+ assertFalse(SetupWizardState.isPlausibleCallsign(it), "'$it' must be refused")
+ }
+ }
+
+ @Test
+ fun onlyASixCharacterLocatorIsAccepted() {
+ listOf("JO50AA", "jo50aa", " JN49FL ").forEach {
+ assertTrue(SetupWizardState.isLocator(it), "'$it' must be accepted")
+ }
+ listOf("", "JO50", "JO50AAA", "SS50AA", "JO50YY", "JO5OAA").forEach {
+ assertFalse(SetupWizardState.isLocator(it), "'$it' must be refused")
+ }
+ }
+
+ @Test
+ fun theCategoryIsSuggestedFromTheLowestBand() {
+ assertNull(SetupWizardState.suggestCategory(emptySet()))
+ assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B50, WizardBand.B144)))
+ assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B70)))
+ assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B144, WizardBand.B1240)))
+ assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B432)))
+ assertEquals(3, SetupWizardState.suggestCategory(setOf(WizardBand.B1240, WizardBand.B10G)))
+ }
+
+ @Test
+ fun theSuggestionFollowsTheBandsUntilTheOperatorChooses() {
+ val state = SetupWizardState(freshInstallation())
+
+ state.setBand(WizardBand.B1240, true)
+ assertEquals(3, state.category)
+
+ state.setBand(WizardBand.B144, true)
+ assertEquals(2, state.category)
+
+ state.chooseCategory(3)
+ state.setBand(WizardBand.B50, true)
+ assertEquals(3, state.category, "an operator's choice is not overwritten")
+ assertEquals(1, state.suggestedCategory, "the suggestion is still shown")
+ }
+
+ @Test
+ fun aSecondChatNeedsADifferentCategory() {
+ val state = SetupWizardState(freshInstallation())
+ state.fillFirstInstallation()
+ assertTrue(state.canGoNext)
+
+ state.chooseSecondChat(true)
+ assertFalse(state.canGoNext, "the second chat has no category yet")
+ assertFalse(state.secondCategoryOptions.contains(2), "the main category is not offered twice")
+
+ state.secondCategory = 3
+ assertTrue(state.canGoNext)
+
+ state.chooseCategory(3)
+ assertNull(state.secondCategory, "the same chat cannot be opened twice")
+ assertFalse(state.canGoNext)
+ }
+
+ @Test
+ fun finishNeedsEveryMandatoryAnswer() {
+ val state = SetupWizardState(freshInstallation())
+
+ state.name = "Philipp"
+ assertFalse(state.canFinish)
+ state.next()
+ state.callsign = "DL0TEST"
+ state.password = "secret"
+ assertFalse(state.canFinish, "a new station still lacks its locator")
+ state.next()
+ state.locator = "JO50AA"
+ assertFalse(state.canFinish, "no band yet")
+ state.setBand(WizardBand.B144, true)
+ assertTrue(state.canFinish)
+
+ state.finish()
+ assertEquals(WizardPage.SUMMARY, state.page)
+ assertTrue(state.mandatoryComplete)
+ assertFalse(state.canFinish, "the summary has Save instead")
+ }
+
+ @Test
+ fun aKeptStationLetsTheOperatorFinishAfterTheLogin() {
+ val state = SetupWizardState(duplicatedProfile())
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.name = "Philipp"
+ state.next()
+ state.callsign = "DL0TEST/P"
+ state.password = "secret"
+
+ assertTrue(state.canFinish)
+ }
+
+ @Test
+ fun aRefusedEntryIsOnlyShownOnceSomethingWasTyped() {
+ val state = SetupWizardState(freshInstallation())
+
+ assertFalse(state.callsignRefused, "an empty field is not an error yet")
+ state.callsign = "DL"
+ assertTrue(state.callsignRefused)
+ state.callsign = "DL0TEST"
+ assertFalse(state.callsignRefused)
+
+ assertFalse(state.locatorRefused)
+ state.locator = "JO50"
+ assertTrue(state.locatorRefused)
+ }
+
+ @Test
+ fun changeFromTheSummaryOpensAStepThatWasSkipped() {
+ val state = SetupWizardState(configuredProfile())
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.next()
+ assertEquals(WizardPage.SUMMARY, state.page)
+
+ state.edit(WizardPage.LOGIN)
+
+ assertEquals(WizardPage.LOGIN, state.page)
+ assertEquals("DL0TEST", state.callsign, "the kept value is there to be changed")
+ state.callsign = "DL0TEST/P"
+ state.next()
+ assertEquals(WizardPage.SUMMARY, state.page)
+ }
+
+ @Test
+ fun theSummarySaysWhatIsSwitchedOffAndWhatIsLeftAlone() {
+ val fresh = SetupWizardState(freshInstallation())
+ assertTrue(fresh.turnsOffSecondChat, "the template has the second chat on, a new station has it off")
+ assertTrue(fresh.leavesIntegrationsUntouched)
+
+ val kept = SetupWizardState(duplicatedProfile())
+ kept.chooseStationSource(WizardSource.KEEP)
+ kept.next()
+ assertFalse(kept.turnsOffSecondChat)
+ assertFalse(kept.leavesIntegrationsUntouched)
+ }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'`
+Expected: Kompilierfehler, `Unresolved reference: SetupWizardState`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import kst4contest.controller.LoginConfiguration
+import kst4contest.model.ChatCategory
+import kst4contest.model.ChatPreferences
+
+/** Where the answers of one group come from. */
+enum class WizardSource {
+ /** Entered in the wizard, starting from the wizard's own empty values. */
+ NEW,
+
+ /** What the profile already holds. */
+ KEEP,
+}
+
+/** The pages, in the order they can appear. */
+enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY }
+
+/**
+ * A band the station can be active on.
+ *
+ * The labels are amateur shorthand and deliberately not in the translation files.
+ */
+enum class WizardBand(
+ val label: String,
+ val megahertz: Int,
+ internal val isActive: (ChatPreferences) -> Boolean,
+ internal val setActive: (ChatPreferences, Boolean) -> Unit,
+) {
+ B50("50 MHz", 50, { it.isStn_bandActive50() }, { p, on -> p.setStn_bandActive50(on) }),
+ B70("70 MHz", 70, { it.isStn_bandActive70() }, { p, on -> p.setStn_bandActive70(on) }),
+ B144("144 MHz", 144, { it.isStn_bandActive144() }, { p, on -> p.setStn_bandActive144(on) }),
+ B432("432 MHz", 432, { it.isStn_bandActive432() }, { p, on -> p.setStn_bandActive432(on) }),
+ B1240("1240 MHz", 1240, { it.isStn_bandActive1240() }, { p, on -> p.setStn_bandActive1240(on) }),
+ B2300("2300 MHz", 2300, { it.isStn_bandActive2300() }, { p, on -> p.setStn_bandActive2300(on) }),
+ B3400("3400 MHz", 3400, { it.isStn_bandActive3400() }, { p, on -> p.setStn_bandActive3400(on) }),
+ B5600("5600 MHz", 5600, { it.isStn_bandActive5600() }, { p, on -> p.setStn_bandActive5600(on) }),
+ B10G("10 GHz", 10000, { it.isStn_bandActive10G() }, { p, on -> p.setStn_bandActive10G(on) }),
+}
+
+/**
+ * The setup wizard's answers and the rules of its course, free of any window.
+ *
+ * It reads the preferences once, when it is built, and does not touch them again until
+ * [writeTo]: closing the wizard without saving therefore leaves the profile exactly as it
+ * was. The design is in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`.
+ *
+ * The answers are Compose state, so a composition reading them follows; nothing else here
+ * depends on Compose.
+ *
+ * @param prefs the profile's preferences, already read from its file
+ */
+class SetupWizardState(prefs: ChatPreferences) {
+
+ private val loginConfigured = !LoginConfiguration.isUnconfigured(prefs)
+ private val templateCredentials = LoginConfiguration.carriesTemplateCredentials(prefs)
+
+ /** The callsign the profile holds, for the label of "leave unchanged". */
+ val storedCallsign: String = prefs.getStn_loginCallSign().orEmpty()
+ private val storedPassword: String = prefs.getStn_loginPassword().orEmpty()
+ private val storedName: String = prefs.getStn_loginNameMainCat().orEmpty()
+ private val storedSecondName: String = prefs.getStn_loginNameSecondCat().orEmpty()
+
+ /** The locator the profile holds, for the label of "leave unchanged". */
+ val storedLocator: String = prefs.getStn_loginLocatorMainCat().orEmpty()
+ private val storedBands: Set = WizardBand.entries.filter { it.isActive(prefs) }.toSet()
+ private val storedCategory: Int? = prefs.getLoginChatCategoryMain()?.categoryNumber
+ private val storedSecondChat: Boolean = prefs.isLoginToSecondChatEnabled()
+ private val storedSecondCategory: Int? = prefs.getLoginChatCategorySecond()?.categoryNumber
+
+ /** A login can only be kept where an operator entered one. */
+ val loginSources: List = buildList {
+ add(WizardSource.NEW)
+ if (loginConfigured) add(WizardSource.KEEP)
+ }
+
+ /**
+ * A station can be kept unless the profile is the untouched template: its locator and
+ * bands are then nobody's.
+ */
+ val stationSources: List = buildList {
+ add(WizardSource.NEW)
+ if (!templateCredentials) add(WizardSource.KEEP)
+ }
+
+ /** Whether there is anything to choose on the entry page. */
+ val hasEntryPage: Boolean = loginSources.size > 1 || stationSources.size > 1
+
+ var loginSource: WizardSource? by mutableStateOf(loginSources.singleOrNull())
+ private set
+
+ var stationSource: WizardSource? by mutableStateOf(stationSources.singleOrNull())
+ private set
+
+ private var appliedLoginSource: WizardSource? = null
+ private var appliedStationSource: WizardSource? = null
+
+ /** The stored form of the language: a code, or empty for the system language. */
+ var language: String by mutableStateOf(prefs.getGuiOptions_language().orEmpty())
+
+ /** Empty on an unconfigured profile: its stored name is the template's or another operator's. */
+ var name: String by mutableStateOf(if (loginConfigured) storedName else "")
+
+ var callsign: String by mutableStateOf("")
+ var password: String by mutableStateOf("")
+ var locator: String by mutableStateOf("")
+
+ var bands: Set by mutableStateOf(emptySet())
+ private set
+
+ var category: Int? by mutableStateOf(null)
+ private set
+
+ private var categoryChosenByOperator = false
+
+ var secondChat: Boolean by mutableStateOf(false)
+ private set
+
+ var secondCategory: Int? by mutableStateOf(null)
+
+ private var loginShown by mutableStateOf(false)
+ private var stationShown by mutableStateOf(false)
+
+ var page: WizardPage by mutableStateOf(if (hasEntryPage) WizardPage.ENTRY else WizardPage.PERSONAL)
+ private set
+
+ init {
+ if (!hasEntryPage) applySources()
+ }
+
+ fun chooseLoginSource(source: WizardSource) {
+ if (source in loginSources) loginSource = source
+ }
+
+ fun chooseStationSource(source: WizardSource) {
+ if (source in stationSources) stationSource = source
+ }
+
+ /**
+ * Loads the answers of a group whose source changed. A group whose source is the one
+ * already applied is left alone, so going back to the entry page costs nothing typed.
+ */
+ private fun applySources() {
+ if (loginSource != appliedLoginSource) {
+ val keep = loginSource == WizardSource.KEEP
+ callsign = if (keep) storedCallsign else ""
+ password = if (keep) storedPassword else ""
+ loginShown = !keep
+ appliedLoginSource = loginSource
+ }
+
+ if (stationSource != appliedStationSource) {
+ val keep = stationSource == WizardSource.KEEP
+ locator = if (keep) storedLocator else ""
+ bands = if (keep) storedBands else emptySet()
+ category = if (keep) storedCategory else null
+ secondChat = keep && storedSecondChat
+ secondCategory = if (keep) storedSecondCategory else null
+ // A kept category is the operator's; the suggestion must not replace it.
+ categoryChosenByOperator = keep
+ stationShown = !keep
+ appliedStationSource = stationSource
+ }
+ }
+
+ fun setBand(band: WizardBand, active: Boolean) {
+ bands = if (active) bands + band else bands - band
+ if (!categoryChosenByOperator) setCategory(suggestCategory(bands))
+ }
+
+ /** What the bands suggest, shown beside the picker whatever is chosen. */
+ val suggestedCategory: Int?
+ get() = suggestCategory(bands)
+
+ fun chooseCategory(number: Int) {
+ categoryChosenByOperator = true
+ setCategory(number)
+ }
+
+ private fun setCategory(number: Int?) {
+ category = number
+ if (secondCategory == number) secondCategory = null
+ }
+
+ fun chooseSecondChat(enabled: Boolean) {
+ secondChat = enabled
+ }
+
+ /** The main category is left out, as the Station tab does. */
+ val secondCategoryOptions: List
+ get() = CATEGORY_NUMBERS.filter { it != category }
+
+ /** The pages of this run, in order. */
+ val pages: List
+ get() = buildList {
+ if (hasEntryPage) add(WizardPage.ENTRY)
+ add(WizardPage.PERSONAL)
+ if (loginShown) add(WizardPage.LOGIN)
+ if (stationShown) add(WizardPage.SITE)
+ add(WizardPage.SUMMARY)
+ }
+
+ private val personalComplete: Boolean
+ get() = name.isNotBlank()
+
+ private val loginComplete: Boolean
+ get() = isPlausibleCallsign(callsign) && password.isNotEmpty()
+
+ private val stationComplete: Boolean
+ get() = isLocator(locator) && bands.isNotEmpty() && category != null &&
+ (!secondChat || (secondCategory != null && secondCategory != category))
+
+ /** Whether everything the profile needs to log in is there. */
+ val mandatoryComplete: Boolean
+ get() = personalComplete && loginComplete && stationComplete
+
+ /** A callsign that was typed and does not look like one. An empty field is not an error yet. */
+ val callsignRefused: Boolean
+ get() = callsign.isNotBlank() && !isPlausibleCallsign(callsign)
+
+ /** A locator that was typed and is not one. An empty field is not an error yet. */
+ val locatorRefused: Boolean
+ get() = locator.isNotBlank() && !isLocator(locator)
+
+ val canGoNext: Boolean
+ get() = when (page) {
+ WizardPage.ENTRY -> loginSource != null && stationSource != null
+ WizardPage.PERSONAL -> personalComplete
+ WizardPage.LOGIN -> loginComplete
+ WizardPage.SITE -> stationComplete
+ WizardPage.SUMMARY -> false
+ }
+
+ val canGoBack: Boolean
+ get() = pages.indexOf(page) > 0
+
+ /**
+ * Whether the remaining steps may be skipped. Only with every mandatory answer, because
+ * a summary that cannot be saved helps nobody.
+ */
+ val canFinish: Boolean
+ get() = page != WizardPage.ENTRY && page != WizardPage.SUMMARY && mandatoryComplete
+
+ fun next() {
+ if (!canGoNext) return
+ if (page == WizardPage.ENTRY) applySources()
+ page = pages[pages.indexOf(page) + 1]
+ }
+
+ fun back() {
+ if (canGoBack) page = pages[pages.indexOf(page) - 1]
+ }
+
+ fun finish() {
+ if (canFinish) page = WizardPage.SUMMARY
+ }
+
+ /** Opens a step from the summary, also one this run skipped. */
+ fun edit(target: WizardPage) {
+ when (target) {
+ WizardPage.LOGIN -> loginShown = true
+ WizardPage.SITE -> stationShown = true
+ WizardPage.PERSONAL -> Unit
+ WizardPage.ENTRY, WizardPage.SUMMARY -> return
+ }
+ page = target
+ }
+
+ /** The profile had a second chat and will have none. */
+ val turnsOffSecondChat: Boolean
+ get() = storedSecondChat && !secondChat
+
+ /**
+ * A new station is set up, and this stage does not ask about log program, rotator,
+ * AirScout and DX cluster server: they keep their stored values, and the summary says so.
+ */
+ val leavesIntegrationsUntouched: Boolean
+ get() = stationSource == WizardSource.NEW
+
+ companion object {
+
+ /** The categories the pickers offer, the way the Station tab builds them. */
+ val CATEGORY_NUMBERS: List = ChatCategory(0).possibleCategoryNumbers.toList()
+
+ private val CALLSIGN = Regex("[A-Za-z0-9]+([-/][A-Za-z0-9]+)?")
+ private val LOCATOR = Regex("[A-Ra-r]{2}[0-9]{2}[A-Xa-x]{2}")
+
+ /**
+ * Whether a text can be a login callsign: letters and digits, at most one "-" or "/"
+ * suffix, and a base of three characters with a letter and a digit. Deliberately
+ * loose -- ON4KST decides what it accepts, this only catches a slip.
+ */
+ fun isPlausibleCallsign(text: String): Boolean {
+ val trimmed = text.trim()
+ if (!CALLSIGN.matches(trimmed)) return false
+ val base = trimmed.substringBefore('-').substringBefore('/')
+ return base.length >= 3 && base.any(Char::isDigit) && base.any(Char::isLetter)
+ }
+
+ /** Whether a text is a six-character Maidenhead locator, in either case. */
+ fun isLocator(text: String): Boolean = LOCATOR.matches(text.trim())
+
+ /**
+ * The chat category the lowest band belongs to: 1 for 50/70 MHz, 2 for 144/432 MHz,
+ * 3 above. Null without a band. A suggestion only -- the operator confirms it.
+ */
+ fun suggestCategory(bands: Set): Int? {
+ val lowest = bands.minOfOrNull { it.megahertz } ?: return null
+ return when {
+ lowest <= 70 -> ChatCategory.FIFTYSEVENTYMHz
+ lowest <= 432 -> ChatCategory.VUHF
+ else -> ChatCategory.MICROWAVE
+ }
+ }
+ }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'`
+Expected: 16 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardStateTest.xml`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt
+git commit -m "Add setup wizard state and its course rules"
+```
+
+---
+
+### Task 3: Antworten in die Profildatei schreiben
+
+**Files:**
+- Modify: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (Methode `writeTo` vor dem `companion object` ergänzen)
+- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt`
+
+**Interfaces:**
+- Consumes: `SetupWizardState` aus Task 2; Setter und `writePreferencesToXmlFile()` von `ChatPreferences`.
+- Produces: `fun SetupWizardState.writeTo(prefs: ChatPreferences): Boolean` — setzt die Antworten und schreibt die Datei; `false`, wenn Pflichtangaben fehlen oder das Schreiben scheitert. Bei fehlenden Pflichtangaben wird `prefs` nicht angefasst.
+
+- [ ] **Step 1: Write the failing test**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import kst4contest.model.ChatCategory
+import kst4contest.model.ChatPreferences
+import org.junit.jupiter.api.Assertions.assertArrayEquals
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.io.TempDir
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardCopyOption
+
+/**
+ * What the wizard does to a real preferences file: nothing until Save, exactly the answers
+ * afterwards, and every setting it never asked about left as it was.
+ */
+class SetupWizardWriteTest(@TempDir private val directory: Path) {
+
+ /** A copy of the bundled template, read the way the runtime reads a profile. */
+ private fun templateFile(): Path {
+ val file = directory.resolve("preferences.xml")
+ ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template ->
+ Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING)
+ }
+ return file
+ }
+
+ private fun read(file: Path): ChatPreferences =
+ ChatPreferences(file).also { assertTrue(it.readPreferencesFromXmlFile(), "reading $file failed") }
+
+ /** A profile an operator set up: read the template, change it, write it back. */
+ private fun configuredFile(change: ChatPreferences.() -> Unit = {}): Path {
+ val file = templateFile()
+ read(file).apply {
+ setStn_loginCallSign("DL0TEST")
+ setStn_loginPassword("secret")
+ setStn_loginNameMainCat("Philipp")
+ setStn_loginNameSecondCat("Philipp")
+ setStn_loginLocatorMainCat("JO50AA")
+ setStn_bandActive144(true)
+ setLoginChatCategoryMain(ChatCategory(2))
+ setLoginToSecondChatEnabled(false)
+ change()
+ assertTrue(writePreferencesToXmlFile())
+ }
+ return file
+ }
+
+ private fun SetupWizardState.answerFirstInstallation() {
+ name = "Philipp"
+ next()
+ callsign = "DL0TEST"
+ password = "secret"
+ next()
+ locator = "JO50AA"
+ setBand(WizardBand.B144, true)
+ setBand(WizardBand.B1240, true)
+ finish()
+ }
+
+ @Test
+ fun nothingIsWrittenBeforeSave() {
+ val file = templateFile()
+ val prefs = read(file)
+ // Taken after the read, so only the wizard is measured here.
+ val before = Files.readAllBytes(file)
+
+ SetupWizardState(prefs).answerFirstInstallation()
+
+ assertArrayEquals(before, Files.readAllBytes(file), "the file changed without Save")
+ assertEquals("DO5AMF", prefs.getStn_loginCallSign(), "the preferences changed without Save")
+ }
+
+ @Test
+ fun saveWritesExactlyTheAnswers() {
+ val file = templateFile()
+ val prefs = read(file)
+ val state = SetupWizardState(prefs)
+ state.answerFirstInstallation()
+
+ assertTrue(state.writeTo(prefs))
+
+ val restored = read(file)
+ assertEquals("DL0TEST", restored.getStn_loginCallSign())
+ assertEquals("secret", restored.getStn_loginPassword())
+ assertEquals("Philipp", restored.getStn_loginNameMainCat())
+ assertEquals("JO50AA", restored.getStn_loginLocatorMainCat())
+ assertTrue(restored.isStn_bandActive144())
+ assertTrue(restored.isStn_bandActive1240())
+ assertFalse(restored.isStn_bandActive432(), "a band the operator did not tick is off")
+ assertEquals(2, restored.getLoginChatCategoryMain().categoryNumber)
+ assertFalse(restored.isLoginToSecondChatEnabled(), "a new station starts without a second chat")
+ }
+
+ @Test
+ fun whatTheWizardNeverAskedAboutIsLeftAsItWas() {
+ val file = templateFile()
+ val prefs = read(file)
+ val server = prefs.getStn_on4kstServersDns()
+ val rotatorPort = prefs.getStn_pstRotatorPort()
+ val udpListener = prefs.isLogsynch_ucxUDPWkdCallListenerEnabled()
+ val clusterServer = prefs.isNotify_dxClusterServerEnabled()
+ val airScout = prefs.isAirScout_asUDPListenerEnabled()
+ val beamWidth = prefs.getStn_antennaBeamWidthDeg()
+
+ val state = SetupWizardState(prefs)
+ state.answerFirstInstallation()
+ assertTrue(state.writeTo(prefs))
+
+ val restored = read(file)
+ assertEquals(server, restored.getStn_on4kstServersDns())
+ assertEquals(rotatorPort, restored.getStn_pstRotatorPort())
+ assertEquals(udpListener, restored.isLogsynch_ucxUDPWkdCallListenerEnabled())
+ assertEquals(clusterServer, restored.isNotify_dxClusterServerEnabled())
+ assertEquals(airScout, restored.isAirScout_asUDPListenerEnabled())
+ assertEquals(beamWidth, restored.getStn_antennaBeamWidthDeg())
+ }
+
+ @Test
+ fun aCallsignIsStoredAsTyped() {
+ val file = templateFile()
+ val prefs = read(file)
+ val state = SetupWizardState(prefs)
+ state.name = "Philipp"
+ state.next()
+ state.callsign = " do5amf-2 "
+ state.password = "secret"
+ state.next()
+ state.locator = " jo50aa "
+ state.setBand(WizardBand.B144, true)
+
+ assertTrue(state.writeTo(prefs))
+
+ val restored = read(file)
+ assertEquals("do5amf-2", restored.getStn_loginCallSign(), "only the surrounding blanks go")
+ assertEquals("jo50aa", restored.getStn_loginLocatorMainCat(), "the Station tab stores it as typed too")
+ }
+
+ @Test
+ fun aKeptCategoryOutsideTheSuggestionsSurvives() {
+ val file = configuredFile {
+ setLoginChatCategoryMain(ChatCategory(7))
+ setLoginToSecondChatEnabled(true)
+ setLoginChatCategorySecond(ChatCategory(9))
+ }
+ val prefs = read(file)
+ val state = SetupWizardState(prefs)
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.next()
+
+ assertTrue(state.writeTo(prefs))
+
+ val restored = read(file)
+ assertEquals(7, restored.getLoginChatCategoryMain().categoryNumber)
+ assertTrue(restored.isLoginToSecondChatEnabled())
+ assertEquals(9, restored.getLoginChatCategorySecond().categoryNumber)
+ }
+
+ @Test
+ fun theSecondNameFollowsTheFirstUnlessItWasSetApart() {
+ val following = configuredFile()
+ val prefs = read(following)
+ val state = SetupWizardState(prefs)
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.name = "Marc"
+ state.next()
+ assertTrue(state.writeTo(prefs))
+ assertEquals("Marc", read(following).getStn_loginNameSecondCat())
+
+ val apart = configuredFile { setStn_loginNameSecondCat("Philipp SHF") }
+ val apartPrefs = read(apart)
+ val apartState = SetupWizardState(apartPrefs)
+ apartState.chooseLoginSource(WizardSource.KEEP)
+ apartState.chooseStationSource(WizardSource.KEEP)
+ apartState.next()
+ apartState.name = "Marc"
+ apartState.next()
+ assertTrue(apartState.writeTo(apartPrefs))
+ assertEquals("Philipp SHF", read(apart).getStn_loginNameSecondCat(), "a name set apart is the operator's")
+ }
+
+ @Test
+ fun anUntouchedLanguageStaysEvenIfThisBuildDoesNotKnowIt() {
+ val file = configuredFile { setGuiOptions_language("fr") }
+ val prefs = read(file)
+ val state = SetupWizardState(prefs)
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.next()
+
+ assertTrue(state.writeTo(prefs))
+
+ assertEquals("fr", read(file).getGuiOptions_language())
+ }
+
+ @Test
+ fun incompleteAnswersAreNotWritten() {
+ val file = templateFile()
+ val prefs = read(file)
+ val before = Files.readAllBytes(file)
+ val state = SetupWizardState(prefs)
+ state.name = "Philipp"
+
+ assertFalse(state.writeTo(prefs))
+
+ assertArrayEquals(before, Files.readAllBytes(file))
+ assertEquals("DO5AMF", prefs.getStn_loginCallSign())
+ }
+
+ @Test
+ fun aFailedWriteIsReported() {
+ val source = read(templateFile())
+ // A directory where the file should be: the write cannot succeed.
+ val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file")))
+ val state = SetupWizardState(source)
+ state.answerFirstInstallation()
+
+ assertFalse(state.writeTo(unwritable), "a write that failed must not read as saved")
+ }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'`
+Expected: Kompilierfehler, `Unresolved reference: writeTo`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `SetupWizardState.kt` unmittelbar vor `companion object {` einfügen:
+
+```kotlin
+ /**
+ * Puts the answers into [prefs] and writes its file.
+ *
+ * Everything the wizard did not ask about stays as [prefs] read it, because the whole
+ * file is read and written back. The callsign and the locator are stored as typed, the
+ * way the Station tab stores them; only surrounding blanks go.
+ *
+ * The second chat's name follows the first unless the operator had set it apart, and the
+ * second category is left alone while the second chat is off.
+ *
+ * @return false when a mandatory answer is missing -- nothing is touched then -- or when
+ * the file could not be written
+ */
+ fun writeTo(prefs: ChatPreferences): Boolean {
+ if (!mandatoryComplete) return false
+
+ val newName = name.trim()
+
+ prefs.setGuiOptions_language(language)
+ prefs.setStn_loginNameMainCat(newName)
+ if (storedSecondName.isBlank() || storedSecondName == storedName) {
+ prefs.setStn_loginNameSecondCat(newName)
+ }
+
+ prefs.setStn_loginCallSign(callsign.trim())
+ prefs.setStn_loginPassword(password)
+
+ prefs.setStn_loginLocatorMainCat(locator.trim())
+ WizardBand.entries.forEach { it.setActive(prefs, it in bands) }
+ prefs.setLoginChatCategoryMain(ChatCategory(requireNotNull(category)))
+ prefs.setLoginToSecondChatEnabled(secondChat)
+ if (secondChat) {
+ prefs.setLoginChatCategorySecond(ChatCategory(requireNotNull(secondCategory)))
+ }
+
+ // A write that throws is a write that failed; the wizard must stay open either way.
+ return runCatching { prefs.writePreferencesToXmlFile() }.getOrDefault(false)
+ }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'`
+Expected: 9 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardWriteTest.xml`.
+
+Schlägt `aFailedWriteIsReported` fehl, weil `writePreferencesToXmlFile` für ein Verzeichnis `true` liefert: **nicht** den Test abschwächen. Den Befund melden — dann meldet auch „Save settings" im Einstellungsfenster einen Erfolg, den es nicht gab, und das ist ein eigener Fehler in `ChatPreferences`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt
+git commit -m "Write setup wizard answers to the profile's preferences file"
+```
+
+---
+
+### Task 4: Die Seiten des Assistenten
+
+**Files:**
+- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt`
+- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `app-desktop/src/main/i18n/strings_de.properties` (Schlüssel am Dateiende anfügen)
+- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt`
+
+**Interfaces:**
+- Consumes: `SetupWizardState`, `WizardPage`, `WizardSource`, `WizardBand` (Task 2); `Form`, `Density`, `Kst4ContestTheme` aus `kst4contest.view.compose`; `LanguageStore`, `LocalStrings`, `Strings`, `Translations`, `SYSTEM_LANGUAGE` aus `kst4contest.view.i18n`; vorhandene Texte `stationCallsign`, `stationPassword`, `stationLocator`, `stationMainCategory`, `stationSecondCategory`, `guiLanguage`, `guiLanguageSystem`.
+- Produces:
+ - `@Composable fun SetupWizardContent(state: SetupWizardState, languageStore: LanguageStore, saveFailed: Boolean, onLater: () -> Unit, onSave: (connect: Boolean) -> Unit)`
+ - `fun wizardLanguageStore(state: SetupWizardState): LanguageStore` — ein `LanguageStore`, dessen Wahl in `state.language` landet und nicht in den Einstellungen
+ - die Textschlüssel `wizard.*` (als `strings.wizard…` erzeugt)
+
+- [ ] **Step 1: Texte anlegen**
+
+An das Ende von `app-desktop/src/main/i18n/strings_en.properties` anfügen:
+
+```properties
+wizard.title=Setup assistant
+wizard.later=Later
+wizard.back=Back
+wizard.next=Next
+wizard.finish=Finish
+wizard.save=Save
+wizard.saveAndConnect=Save and connect
+wizard.change=Change
+wizard.saveFailed=The settings could not be written. Nothing was changed.
+wizard.missing=Some required entries are still missing. Use Change to complete them.
+wizard.entry.title=Where do the entries come from?
+wizard.entry.lead=Choose separately for login and station.
+wizard.entry.login=Login (callsign, password)
+wizard.entry.station=Station (locator, bands, chat category)
+wizard.source.loginNew=Enter a new login
+wizard.source.loginKeep=Leave the login unchanged ({0})
+wizard.source.stationNew=Set up a new station
+wizard.source.stationKeep=Leave the station unchanged (locator {0})
+wizard.personal.title=Personal
+wizard.personal.lead=Belongs to the operator.
+wizard.personal.name=Name shown in the chat
+wizard.login.title=ON4KST login
+wizard.login.lead=The credentials of your ON4KST account.
+wizard.login.callsignInvalid=This does not look like a callsign.
+wizard.site.title=Location and bands
+wizard.site.lead=Belongs to the station, not to the operator.
+wizard.site.locatorInvalid=Six-character Maidenhead locator, for example JO50AA.
+wizard.site.bands=Active bands
+wizard.site.bandsHint=No frequency is derived from the bands.
+wizard.site.categorySuggestion=Suggested from the bands: {0}
+wizard.site.secondChat=Open a second chat
+wizard.summary.title=Summary
+wizard.summary.lead=Nothing is written until you save.
+wizard.summary.personal=Personal
+wizard.summary.login=Login
+wizard.summary.station=Station
+wizard.summary.bands=Bands
+wizard.summary.turnedOff=Will be switched off: second chat.
+wizard.summary.integrationsUnchanged=Log program, rotator, AirScout and DX cluster server keep their stored settings. Check them in the settings window.
+wizard.summary.none=none
+wizard.summary.passwordSet=set
+```
+
+An das Ende von `app-desktop/src/main/i18n/strings_de.properties` anfügen:
+
+```properties
+wizard.title=Einrichtungsassistent
+wizard.later=Später
+wizard.back=Zurück
+wizard.next=Weiter
+wizard.finish=Fertig
+wizard.save=Speichern
+wizard.saveAndConnect=Speichern und verbinden
+wizard.change=Ändern
+wizard.saveFailed=Die Einstellungen konnten nicht geschrieben werden. Es wurde nichts geändert.
+wizard.missing=Es fehlen noch Pflichtangaben. Über „Ändern" ergänzen.
+wizard.entry.title=Woher kommen die Angaben?
+wizard.entry.lead=Für Anmeldung und Station getrennt wählen.
+wizard.entry.login=Anmeldung (Rufzeichen, Passwort)
+wizard.entry.station=Station (Locator, Bänder, Chatkategorie)
+wizard.source.loginNew=Anmeldung neu eingeben
+wizard.source.loginKeep=Anmeldung unverändert lassen ({0})
+wizard.source.stationNew=Station neu einrichten
+wizard.source.stationKeep=Station unverändert lassen (Locator {0})
+wizard.personal.title=Persönliches
+wizard.personal.lead=Gehört zum Operator.
+wizard.personal.name=Anzeigename im Chat
+wizard.login.title=Anmeldung bei ON4KST
+wizard.login.lead=Die Zugangsdaten deines ON4KST-Kontos.
+wizard.login.callsignInvalid=Das sieht nicht nach einem Rufzeichen aus.
+wizard.site.title=Standort und Bänder
+wizard.site.lead=Gehört zur Station, nicht zum Operator.
+wizard.site.locatorInvalid=Sechsstelliger Maidenhead-Locator, zum Beispiel JO50AA.
+wizard.site.bands=Aktive Bänder
+wizard.site.bandsHint=Aus den Bändern wird keine Frequenz abgeleitet.
+wizard.site.categorySuggestion=Vorschlag aus den Bändern: {0}
+wizard.site.secondChat=Zweiten Chat öffnen
+wizard.summary.title=Zusammenfassung
+wizard.summary.lead=Erst „Speichern" schreibt in die Einstellungsdatei.
+wizard.summary.personal=Persönliches
+wizard.summary.login=Anmeldung
+wizard.summary.station=Station
+wizard.summary.bands=Bänder
+wizard.summary.turnedOff=Wird abgeschaltet: Zweitchat.
+wizard.summary.integrationsUnchanged=Logprogramm, Rotor, AirScout und DX-Cluster-Server behalten ihre gespeicherten Werte. Im Einstellungsfenster prüfen.
+wizard.summary.none=keine
+wizard.summary.passwordSet=gesetzt
+```
+
+Run: `./gradlew :app-desktop:compileKotlin`
+Expected: BUILD SUCCESSFUL. Ein Fehler des Erzeugers nennt den Schlüssel; er prüft doppelte Schlüssel, Waisen und die Zahl der Platzhalter.
+
+- [ ] **Step 2: Write the failing test**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import androidx.compose.ui.test.ComposeUiTest
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performClick
+import androidx.compose.ui.test.runComposeUiTest
+import kst4contest.model.ChatCategory
+import kst4contest.model.ChatPreferences
+import kst4contest.view.compose.Kst4ContestTheme
+import kst4contest.view.i18n.LanguageStore
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+import java.nio.file.Path
+import java.util.Locale
+
+/**
+ * The drawn wizard, clicked the way an operator clicks it. The rules live in
+ * SetupWizardState and are tested there; this holds the wiring -- that a button reaches the
+ * state, and that a button which must not work does not.
+ */
+@OptIn(ExperimentalTestApi::class)
+class SetupWizardContentScreenTest {
+
+ private fun configuredProfile() =
+ ChatPreferences(Path.of("setup-wizard-screen-test-unused.xml")).apply {
+ setStn_loginCallSign("DL0TEST")
+ setStn_loginPassword("secret")
+ setStn_loginNameMainCat("Philipp")
+ setStn_loginLocatorMainCat("JO50AA")
+ setStn_bandActive144(true)
+ setLoginChatCategoryMain(ChatCategory(2))
+ // Stated, not left to the compiled-in default: with a second chat and no second
+ // category the summary could not be saved.
+ setLoginToSecondChatEnabled(false)
+ }
+
+ private class Recorded {
+ var later = 0
+ val saves = mutableListOf()
+ }
+
+ private fun ComposeUiTest.show(state: SetupWizardState, saveFailed: Boolean = false): Recorded {
+ val recorded = Recorded()
+ // English, whatever language an earlier test in this JVM left behind.
+ val english = LanguageStore({ "en" }, {}, Locale.ENGLISH)
+ setContent {
+ Kst4ContestTheme(darkMode = false, baseFontSizeSp = 12f) {
+ SetupWizardContent(
+ state = state,
+ languageStore = english,
+ saveFailed = saveFailed,
+ onLater = { recorded.later++ },
+ onSave = { recorded.saves += it },
+ )
+ }
+ }
+ return recorded
+ }
+
+ @Test
+ fun nextDoesNothingUntilBothSourcesAreChosen() = runComposeUiTest {
+ val state = SetupWizardState(configuredProfile())
+ show(state)
+
+ onNodeWithText("Next").performClick()
+ assertEquals(WizardPage.ENTRY, state.page, "Next worked without a choice")
+
+ onNodeWithText("Leave the login unchanged (DL0TEST)").performClick()
+ onNodeWithText("Leave the station unchanged (locator JO50AA)").performClick()
+ assertEquals(WizardSource.KEEP, state.loginSource)
+ assertEquals(WizardSource.KEEP, state.stationSource)
+
+ onNodeWithText("Next").performClick()
+ assertEquals(WizardPage.PERSONAL, state.page)
+ }
+
+ @Test
+ fun laterIsReportedAndNothingElse() = runComposeUiTest {
+ val recorded = show(SetupWizardState(configuredProfile()))
+
+ onNodeWithText("Later").performClick()
+
+ assertEquals(1, recorded.later)
+ assertTrue(recorded.saves.isEmpty())
+ }
+
+ @Test
+ fun theSummaryOffersBothWaysOfSaving() = runComposeUiTest {
+ val state = SetupWizardState(configuredProfile())
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.next()
+ val recorded = show(state)
+
+ onNodeWithText("Save").performClick()
+ onNodeWithText("Save and connect").performClick()
+
+ assertEquals(listOf(false, true), recorded.saves)
+ }
+
+ @Test
+ fun aFailedSaveIsToldToTheOperator() = runComposeUiTest {
+ val state = SetupWizardState(configuredProfile())
+ state.chooseLoginSource(WizardSource.KEEP)
+ state.chooseStationSource(WizardSource.KEEP)
+ state.next()
+ state.next()
+ show(state, saveFailed = true)
+
+ onNodeWithText("The settings could not be written. Nothing was changed.").assertExists()
+ }
+}
+```
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'`
+Expected: Kompilierfehler, `Unresolved reference: SetupWizardContent`.
+
+- [ ] **Step 4: Write minimal implementation**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.selection.selectable
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.RadioButton
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.Role
+import androidx.compose.ui.unit.dp
+import kst4contest.model.ChatCategory
+import kst4contest.view.compose.Density
+import kst4contest.view.compose.Form
+import kst4contest.view.i18n.LanguageStore
+import kst4contest.view.i18n.LocalStrings
+import kst4contest.view.i18n.SYSTEM_LANGUAGE
+import kst4contest.view.i18n.Strings
+import kst4contest.view.i18n.Translations
+
+/**
+ * A language store for the wizard: a choice takes effect on screen at once and is kept in
+ * the wizard's answers, not in the preferences. "Later" therefore stores no language, and
+ * the runtime built afterwards puts the stored one back in force.
+ */
+fun wizardLanguageStore(state: SetupWizardState): LanguageStore =
+ LanguageStore(storedLanguage = { state.language }, storeLanguage = { state.language = it })
+
+/** The name a chat category carries in the pickers, the one the Station tab shows. */
+private fun categoryName(number: Int): String = ChatCategory(number).getChatCategoryName(number)
+
+/**
+ * The wizard's pages and its button row.
+ *
+ * All decisions are in [state]; this draws them. The texts are read from [languageStore] in
+ * the composition, so the language picker on the first page switches the wizard itself.
+ *
+ * @param saveFailed whether the last Save could not write the file
+ * @param onLater the operator does not want to set up now; nothing is written
+ * @param onSave the operator saves; true when the session should be started afterwards
+ */
+@Composable
+fun SetupWizardContent(
+ state: SetupWizardState,
+ languageStore: LanguageStore,
+ saveFailed: Boolean,
+ onLater: () -> Unit,
+ onSave: (connect: Boolean) -> Unit,
+) {
+ val strings = languageStore.strings
+
+ CompositionLocalProvider(LocalStrings provides strings) {
+ Surface(modifier = Modifier.fillMaxSize()) {
+ Column(modifier = Modifier.padding(15.dp)) {
+ Column(
+ modifier = Modifier.weight(1f).fillMaxWidth().verticalScroll(rememberScrollState()),
+ verticalArrangement = Arrangement.spacedBy(6.dp),
+ ) {
+ when (state.page) {
+ WizardPage.ENTRY -> EntryPage(state, strings)
+ WizardPage.PERSONAL -> PersonalPage(state, strings, languageStore)
+ WizardPage.LOGIN -> LoginPage(state, strings)
+ WizardPage.SITE -> SitePage(state, strings)
+ WizardPage.SUMMARY -> SummaryPage(state, strings, saveFailed)
+ }
+ }
+
+ Row(
+ modifier = Modifier.fillMaxWidth().padding(top = 10.dp),
+ horizontalArrangement = Arrangement.spacedBy(Density.BUTTON_GAP),
+ ) {
+ Form.button(strings.wizardLater, onClick = onLater)
+ Spacer(Modifier.weight(1f))
+ if (state.canGoBack) {
+ Form.button(strings.wizardBack, onClick = state::back)
+ }
+ if (state.page == WizardPage.SUMMARY) {
+ Form.button(strings.wizardSave, enabled = state.mandatoryComplete) { onSave(false) }
+ Form.button(
+ strings.wizardSaveAndConnect,
+ enabled = state.mandatoryComplete,
+ accented = true,
+ ) { onSave(true) }
+ } else {
+ if (state.canFinish) {
+ Form.button(strings.wizardFinish, onClick = state::finish)
+ }
+ Form.button(
+ strings.wizardNext,
+ enabled = state.canGoNext,
+ accented = true,
+ onClick = state::next,
+ )
+ }
+ }
+ }
+ }
+ }
+}
+
+@Composable
+private fun Heading(title: String, lead: String) {
+ Text(title, style = MaterialTheme.typography.titleMedium)
+ Text(lead, style = MaterialTheme.typography.bodySmall)
+}
+
+@Composable
+private fun Refusal(text: String) {
+ Text(text, color = MaterialTheme.colorScheme.error, style = MaterialTheme.typography.bodySmall)
+}
+
+@Composable
+private fun SourceOption(label: String, selected: Boolean, onSelect: () -> Unit) {
+ Row(
+ modifier = Modifier
+ .fillMaxWidth()
+ .selectable(selected = selected, role = Role.RadioButton, onClick = onSelect)
+ .padding(vertical = 2.dp),
+ verticalAlignment = Alignment.CenterVertically,
+ ) {
+ RadioButton(selected = selected, onClick = null)
+ Text(label, modifier = Modifier.padding(start = 6.dp))
+ }
+}
+
+@Composable
+private fun EntryPage(state: SetupWizardState, strings: Strings) {
+ Heading(strings.wizardEntryTitle, strings.wizardEntryLead)
+
+ /* An axis with a single option is decided already and is not asked about. */
+ if (state.loginSources.size > 1) {
+ Form.section(strings.wizardEntryLogin) {
+ state.loginSources.forEach { source ->
+ SourceOption(
+ label = when (source) {
+ WizardSource.NEW -> strings.wizardSourceLoginNew
+ WizardSource.KEEP -> strings.wizardSourceLoginKeep(state.storedCallsign)
+ },
+ selected = state.loginSource == source,
+ onSelect = { state.chooseLoginSource(source) },
+ )
+ }
+ }
+ }
+
+ if (state.stationSources.size > 1) {
+ Form.section(strings.wizardEntryStation) {
+ state.stationSources.forEach { source ->
+ SourceOption(
+ label = when (source) {
+ WizardSource.NEW -> strings.wizardSourceStationNew
+ WizardSource.KEEP -> strings.wizardSourceStationKeep(state.storedLocator)
+ },
+ selected = state.stationSource == source,
+ onSelect = { state.chooseStationSource(source) },
+ )
+ }
+ }
+ }
+}
+
+@Composable
+private fun PersonalPage(state: SetupWizardState, strings: Strings, languageStore: LanguageStore) {
+ Heading(strings.wizardPersonalTitle, strings.wizardPersonalLead)
+
+ Form.choice(
+ label = strings.guiLanguage,
+ items = listOf(SYSTEM_LANGUAGE) + Translations.BY_LANGUAGE.keys.sorted(),
+ selected = languageStore.stored,
+ // The code in capitals, as the GUI tab shows it.
+ describe = { code -> if (code == SYSTEM_LANGUAGE) strings.guiLanguageSystem else code.uppercase() },
+ onSelect = { languageStore.use(it) },
+ )
+ Form.text(strings.wizardPersonalName, state.name) { state.name = it }
+}
+
+@Composable
+private fun LoginPage(state: SetupWizardState, strings: Strings) {
+ Heading(strings.wizardLoginTitle, strings.wizardLoginLead)
+
+ Form.text(strings.stationCallsign, state.callsign) { state.callsign = it }
+ if (state.callsignRefused) Refusal(strings.wizardLoginCallsignInvalid)
+ Form.password(strings.stationPassword, state.password) { state.password = it }
+}
+
+@Composable
+private fun SitePage(state: SetupWizardState, strings: Strings) {
+ Heading(strings.wizardSiteTitle, strings.wizardSiteLead)
+
+ Form.text(strings.stationLocator, state.locator) { state.locator = it }
+ if (state.locatorRefused) Refusal(strings.wizardSiteLocatorInvalid)
+
+ Form.flowingSection(strings.wizardSiteBands) {
+ WizardBand.entries.forEach { band ->
+ Form.check(band.label, band in state.bands) { state.setBand(band, it) }
+ }
+ }
+ Text(strings.wizardSiteBandsHint, style = MaterialTheme.typography.bodySmall)
+
+ Form.choice(
+ label = strings.stationMainCategory,
+ items = SetupWizardState.CATEGORY_NUMBERS,
+ selected = state.category,
+ describe = ::categoryName,
+ onSelect = state::chooseCategory,
+ )
+ state.suggestedCategory?.let { suggested ->
+ Text(
+ strings.wizardSiteCategorySuggestion(categoryName(suggested)),
+ style = MaterialTheme.typography.bodySmall,
+ )
+ }
+
+ Form.check(strings.wizardSiteSecondChat, state.secondChat) { state.chooseSecondChat(it) }
+ if (state.secondChat) {
+ Form.choice(
+ label = strings.stationSecondCategory,
+ items = state.secondCategoryOptions,
+ selected = state.secondCategory,
+ describe = ::categoryName,
+ onSelect = { state.secondCategory = it },
+ )
+ }
+}
+
+@Composable
+private fun SummaryRow(label: String, value: String) {
+ Form.labelledRow(label) { Text(value) }
+}
+
+@Composable
+private fun SummaryPage(state: SetupWizardState, strings: Strings, saveFailed: Boolean) {
+ Heading(strings.wizardSummaryTitle, strings.wizardSummaryLead)
+
+ if (saveFailed) Refusal(strings.wizardSaveFailed)
+ if (!state.mandatoryComplete) Refusal(strings.wizardMissing)
+ if (state.turnsOffSecondChat) Text(strings.wizardSummaryTurnedOff)
+ if (state.leavesIntegrationsUntouched) Text(strings.wizardSummaryIntegrationsUnchanged)
+
+ Form.section(strings.wizardSummaryPersonal) {
+ SummaryRow(strings.wizardPersonalName, state.name.ifBlank { strings.wizardSummaryNone })
+ Form.button(strings.wizardChange) { state.edit(WizardPage.PERSONAL) }
+ }
+
+ Form.section(strings.wizardSummaryLogin) {
+ SummaryRow(strings.stationCallsign, state.callsign.ifBlank { strings.wizardSummaryNone })
+ // Never the password itself: the summary may be read over a shoulder.
+ SummaryRow(
+ strings.stationPassword,
+ if (state.password.isEmpty()) strings.wizardSummaryNone else strings.wizardSummaryPasswordSet,
+ )
+ Form.button(strings.wizardChange) { state.edit(WizardPage.LOGIN) }
+ }
+
+ Form.section(strings.wizardSummaryStation) {
+ SummaryRow(strings.stationLocator, state.locator.ifBlank { strings.wizardSummaryNone })
+ SummaryRow(
+ strings.wizardSummaryBands,
+ WizardBand.entries.filter { it in state.bands }.joinToString(", ") { it.label }
+ .ifEmpty { strings.wizardSummaryNone },
+ )
+ SummaryRow(
+ strings.stationMainCategory,
+ state.category?.let(::categoryName) ?: strings.wizardSummaryNone,
+ )
+ SummaryRow(
+ strings.stationSecondCategory,
+ state.secondCategory?.takeIf { state.secondChat }?.let(::categoryName) ?: strings.wizardSummaryNone,
+ )
+ Form.button(strings.wizardChange) { state.edit(WizardPage.SITE) }
+ }
+}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'`
+Expected: 4 Tests, 0 Fehler.
+
+Meldet der Übersetzer, dass `Density.BUTTON_GAP` oder `Form.labelledRow` nicht sichtbar ist: beide werden in `OperatorProfilePickerWindow.kt` bzw. `FormControls.kt` im Paket `kst4contest.view.compose` benutzt. Ist eines davon `internal`, bleibt es das — der Assistent liegt im selben Modul.
+
+- [ ] **Step 6: Die Sprachtests laufen lassen**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.i18n.*'`
+Expected: alle grün. `TranslationBoundaryTest` hält Deutsch vollständig; ein fehlender deutscher Schlüssel fällt hier auf.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt
+git commit -m "Draw the setup wizard pages"
+```
+
+---
+
+### Task 5: Fenster und Starter
+
+**Files:**
+- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt`
+- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt`
+- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt`
+
+**Interfaces:**
+- Consumes: `SetupWizardState`, `writeTo` (Task 2, 3); `SetupWizardContent`, `wizardLanguageStore` (Task 4); `LoginConfiguration.isUnconfigured` (Task 1); `openOnEventThread`, `Kst4ContestTheme`, `WindowPlacementOnScreen.centreOnMainWindowScreen` aus `kst4contest.view.compose`; Testhelfer `kst4contest.testing.Await.awaitUntil`.
+- Produces:
+ - `enum class SetupWizardOutcome { NOT_SHOWN, LATER, SAVED, SAVED_AND_CONNECT }`
+ - `object SetupWizardWindow { fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome }` — blockiert, bis das Fenster zu ist
+ - `object SetupWizardLauncher` mit
+ - `@JvmStatic fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome`
+ - `internal fun run(prefs: ChatPreferences, forced: Boolean, show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome): SetupWizardOutcome`
+ - `internal fun saveFromWizard(state: SetupWizardState, prefs: ChatPreferences, connect: Boolean): SetupWizardOutcome?` — `null`, wenn das Schreiben scheiterte
+
+- [ ] **Step 1: Write the failing tests**
+
+`SetupWizardLauncherTest.kt`:
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import kst4contest.model.ChatPreferences
+import org.junit.jupiter.api.Assertions.assertArrayEquals
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertNull
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.io.TempDir
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardCopyOption
+
+/** When the wizard opens at all, decided without a window. */
+class SetupWizardLauncherTest(@TempDir private val directory: Path) {
+
+ private fun templateFile(): Path {
+ val file = directory.resolve("preferences.xml")
+ ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template ->
+ Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING)
+ }
+ return file
+ }
+
+ private fun configuredFile(): Path {
+ val file = templateFile()
+ ChatPreferences(file).apply {
+ assertTrue(readPreferencesFromXmlFile())
+ setStn_loginCallSign("DL0TEST")
+ setStn_loginPassword("secret")
+ assertTrue(writePreferencesToXmlFile())
+ }
+ return file
+ }
+
+ private val neverShown: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome =
+ { _, _ -> throw AssertionError("the wizard must not open here") }
+
+ @Test
+ fun anUnconfiguredProfileOpensTheWizard() {
+ var shown = 0
+
+ val outcome = SetupWizardLauncher.run(ChatPreferences(templateFile()), forced = false) { _, _ ->
+ shown++
+ SetupWizardOutcome.LATER
+ }
+
+ assertEquals(1, shown)
+ assertEquals(SetupWizardOutcome.LATER, outcome)
+ }
+
+ @Test
+ fun aConfiguredProfileStartsWithoutTheWizard() {
+ assertEquals(
+ SetupWizardOutcome.NOT_SHOWN,
+ SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = false, neverShown),
+ )
+ }
+
+ @Test
+ fun theMenuOpensItOnAConfiguredProfileToo() {
+ val outcome = SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = true) { state, _ ->
+ assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources)
+ SetupWizardOutcome.SAVED
+ }
+
+ assertEquals(SetupWizardOutcome.SAVED, outcome)
+ }
+
+ @Test
+ fun anUnreadableFileNeverOpensTheWizard() {
+ val garbage = directory.resolve("broken.xml")
+ Files.writeString(garbage, "this is not xml <<<")
+ val before = Files.readAllBytes(garbage)
+
+ // Forced as well: a wizard over a file it could not read would save over it.
+ assertEquals(
+ SetupWizardOutcome.NOT_SHOWN,
+ SetupWizardLauncher.run(ChatPreferences(garbage), forced = true, neverShown),
+ )
+ assertArrayEquals(before, Files.readAllBytes(garbage), "the unreadable file was touched")
+ }
+
+ @Test
+ fun aFailedSaveKeepsTheWizardOpen() {
+ val source = ChatPreferences(templateFile()).apply { assertTrue(readPreferencesFromXmlFile()) }
+ val state = SetupWizardState(source).apply {
+ name = "Philipp"
+ next()
+ callsign = "DL0TEST"
+ password = "secret"
+ next()
+ locator = "JO50AA"
+ setBand(WizardBand.B144, true)
+ }
+ val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file")))
+
+ assertNull(saveFromWizard(state, unwritable, connect = true), "a failed write must not close the wizard")
+ }
+
+ @Test
+ fun aSaveReportsWhetherToConnect() {
+ val file = templateFile()
+ val prefs = ChatPreferences(file).apply { assertTrue(readPreferencesFromXmlFile()) }
+ val state = SetupWizardState(prefs).apply {
+ name = "Philipp"
+ next()
+ callsign = "DL0TEST"
+ password = "secret"
+ next()
+ locator = "JO50AA"
+ setBand(WizardBand.B144, true)
+ }
+
+ assertEquals(SetupWizardOutcome.SAVED, saveFromWizard(state, prefs, connect = false))
+ assertEquals(SetupWizardOutcome.SAVED_AND_CONNECT, saveFromWizard(state, prefs, connect = true))
+ }
+}
+```
+
+`SetupWizardWindowTest.kt`:
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import kst4contest.model.ChatPreferences
+import kst4contest.testing.Await.awaitUntil
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assumptions.assumeFalse
+import org.junit.jupiter.api.Test
+import java.awt.EventQueue
+import java.awt.GraphicsEnvironment
+import java.awt.Window
+import java.nio.file.Path
+import java.time.Duration
+import java.util.concurrent.Executors
+import java.util.concurrent.Future
+import java.util.concurrent.TimeUnit
+
+/**
+ * The wizard's dialog must open from both threads that open it: `main` at startup, and the
+ * event thread when the menu rebuilds the runtime. A latch-based wait deadlocked the profile
+ * picker in exactly the second case; see OperatorProfilePickerWindow.
+ */
+class SetupWizardWindowTest {
+
+ private fun prefs() = ChatPreferences(Path.of("setup-wizard-window-test-unused.xml"))
+
+ private fun showingDialog(): Window? =
+ Window.getWindows().firstOrNull { it.isShowing && it.javaClass.name.contains("ComposeDialog") }
+
+ private val closer = Executors.newSingleThreadExecutor()
+
+ /** Closes the dialog the way its X does, as soon as it is on screen. */
+ private fun disposeOnceShowing(): Future<*> =
+ closer.submit {
+ awaitUntil(Duration.ofSeconds(10), "the wizard's dialog never appeared") {
+ showingDialog() != null
+ }
+ EventQueue.invokeLater { showingDialog()?.dispose() }
+ }
+
+ @Test
+ fun closingTheWindowCountsAsLater() {
+ assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display")
+
+ try {
+ val closing = disposeOnceShowing()
+ val prefs = prefs()
+
+ val outcome = SetupWizardWindow.show(SetupWizardState(prefs), prefs)
+
+ assertEquals(SetupWizardOutcome.LATER, outcome)
+ assertEquals("", prefs.getStn_loginCallSign(), "closing the window wrote something")
+ closing.get(1, TimeUnit.SECONDS)
+ } finally {
+ closer.shutdownNow()
+ }
+ }
+
+ @Test
+ fun opensAndReturnsWhenCalledOnTheEventThread() {
+ assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display")
+
+ val worker = Executors.newSingleThreadExecutor()
+ try {
+ val closing = disposeOnceShowing()
+ val prefs = prefs()
+ val call = worker.submit {
+ EventQueue.invokeAndWait { SetupWizardWindow.show(SetupWizardState(prefs), prefs) }
+ }
+
+ // A deadlock here has no timeout of its own: without one this never completes.
+ call.get(20, TimeUnit.SECONDS)
+ closing.get(1, TimeUnit.SECONDS)
+ } finally {
+ worker.shutdownNow()
+ closer.shutdownNow()
+ }
+ }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardLauncherTest' --tests 'kst4contest.view.compose.wizard.SetupWizardWindowTest'`
+Expected: Kompilierfehler, `Unresolved reference: SetupWizardLauncher`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```kotlin
+package kst4contest.view.compose.wizard
+
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.awt.ComposeDialog
+import kst4contest.controller.LoginConfiguration
+import kst4contest.model.ChatPreferences
+import kst4contest.view.compose.Kst4ContestTheme
+import kst4contest.view.compose.WindowPlacementOnScreen
+import kst4contest.view.compose.openOnEventThread
+import java.awt.Dialog
+import java.awt.Dimension
+import java.util.concurrent.atomic.AtomicReference
+import javax.swing.WindowConstants
+
+/** How a run of the setup wizard ended. */
+enum class SetupWizardOutcome {
+ /** The profile is set up, or its file could not be read: the wizard did not open. */
+ NOT_SHOWN,
+
+ /** Closed without saving; the file is as it was. */
+ LATER,
+
+ /** The answers are in the file. */
+ SAVED,
+
+ /** The answers are in the file and the operator wants the session started. */
+ SAVED_AND_CONNECT,
+}
+
+/**
+ * Writes the answers and says how the wizard ends.
+ *
+ * @return the outcome to close with, or null when the file could not be written -- the
+ * wizard then stays open, because "saved" would be a lie
+ */
+internal fun saveFromWizard(
+ state: SetupWizardState,
+ prefs: ChatPreferences,
+ connect: Boolean,
+): SetupWizardOutcome? =
+ when {
+ !state.writeTo(prefs) -> null
+ connect -> SetupWizardOutcome.SAVED_AND_CONNECT
+ else -> SetupWizardOutcome.SAVED
+ }
+
+/**
+ * The setup wizard's window.
+ *
+ * A modal [ComposeDialog] opened through [openOnEventThread], the construction
+ * OperatorProfilePickerWindow uses and for the reason given there: a wait that does not
+ * pump events deadlocks once the caller is the event thread, and this one is called from
+ * `main` at startup and from the event thread when the menu rebuilds the runtime.
+ */
+object SetupWizardWindow {
+
+ /** Runs before a profile's runtime exists, so there is no configured size to read. */
+ private const val DIALOG_FONT_SIZE_SP = 12f
+
+ private val DIALOG_SIZE = Dimension(640, 620)
+
+ /**
+ * Opens the wizard and blocks until it is closed.
+ *
+ * @param prefs the profile's preferences; written only by Save
+ * @return never [SetupWizardOutcome.NOT_SHOWN]
+ */
+ fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome {
+ /* The window's X leaves this untouched: closing is "later". */
+ val outcome = AtomicReference(SetupWizardOutcome.LATER)
+
+ openOnEventThread { open(state, prefs, outcome) }
+
+ return outcome.get()
+ }
+
+ private fun open(
+ state: SetupWizardState,
+ prefs: ChatPreferences,
+ outcome: AtomicReference,
+ ) {
+ val languageStore = wizardLanguageStore(state)
+ var saveFailed by mutableStateOf(false)
+
+ val dialog = ComposeDialog(owner = null, modalityType = Dialog.ModalityType.APPLICATION_MODAL)
+ dialog.title = languageStore.strings.wizardTitle
+ dialog.size = DIALOG_SIZE
+ WindowPlacementOnScreen.centreOnMainWindowScreen(dialog)
+ /* Disposed and not hidden: a hidden dialog keeps its window and Skia layer alive. */
+ dialog.defaultCloseOperation = WindowConstants.DISPOSE_ON_CLOSE
+
+ dialog.setContent {
+ Kst4ContestTheme(
+ darkMode = prefs.isGUI_darkModeActiveByDefault(),
+ baseFontSizeSp = DIALOG_FONT_SIZE_SP,
+ ) {
+ SetupWizardContent(
+ state = state,
+ languageStore = languageStore,
+ saveFailed = saveFailed,
+ onLater = { dialog.dispose() },
+ onSave = { connect ->
+ val saved = saveFromWizard(state, prefs, connect)
+ if (saved == null) {
+ saveFailed = true
+ } else {
+ outcome.set(saved)
+ dialog.dispose()
+ }
+ },
+ )
+ }
+ }
+
+ dialog.isVisible = true
+ }
+}
+
+/** Decides whether the wizard opens for a profile, and opens it. */
+object SetupWizardLauncher {
+
+ /**
+ * Opens the wizard when the profile needs it, before the profile's runtime is built.
+ *
+ * @param preferencesRelativeFileName the profile's preferences file below the
+ * application directory; a missing one is seeded from the bundled template, as
+ * the runtime itself would do
+ * @param forced the operator asked for the wizard from the menu
+ */
+ @JvmStatic
+ fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome =
+ run(ChatPreferences(preferencesRelativeFileName), forced, SetupWizardWindow::show)
+
+ /**
+ * @param prefs bound to the profile's file and not read yet
+ * @param show opens the window; replaced in the tests
+ */
+ internal fun run(
+ prefs: ChatPreferences,
+ forced: Boolean,
+ show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome,
+ ): SetupWizardOutcome {
+ /*
+ * A file that cannot be read is not a profile to set up: the wizard would start from
+ * compiled-in defaults and Save would write them over whatever the file holds. The
+ * runtime deals with such a file as it always did.
+ */
+ if (!prefs.readPreferencesFromXmlFile()) return SetupWizardOutcome.NOT_SHOWN
+
+ if (!forced && !LoginConfiguration.isUnconfigured(prefs)) return SetupWizardOutcome.NOT_SHOWN
+
+ return show(SetupWizardState(prefs), prefs)
+ }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.*'`
+Expected: alle Tests der vier Klassen grün; `SetupWizardWindowTest` läuft nur mit Bildschirm und wird sonst übersprungen (`skipped` in der XML, kein Fehler).
+
+Liefert `readPreferencesFromXmlFile` für die kaputte Datei `true`: den Test nicht abschwächen, den Befund melden. Dann liest `ChatPreferences` Müll als gültig, und das betrifft auch den normalen Start.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt
+git commit -m "Open the setup wizard as a modal dialog"
+```
+
+---
+
+### Task 6: Der Assistent im Programmstart
+
+**Files:**
+- Modify: `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java`
+- Modify: `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` (Methode `startRuntime`, ab Zeile 2174)
+- Test: `app-desktop/src/test/java/kst4contest/view/ApplicationRuntimeLauncherSetupWizardTest.java`
+
+**Interfaces:**
+- Consumes: `SetupWizardLauncher.runIfNeeded(String, boolean)`, `SetupWizardOutcome` (Task 5); `ActiveOperatorProfile.get().getPreferencesRelativeFileName()`; `Kst4ContestApplication.menuActionConnect()`.
+- Produces:
+ - `static void ApplicationRuntimeLauncher.requestSetupWizard()` (paketsichtbar)
+ - `static boolean ApplicationRuntimeLauncher.consumeSetupWizardRequest()` (paketsichtbar) — liefert den Wunsch genau einmal
+
+- [ ] **Step 1: Write the failing test**
+
+```java
+package kst4contest.view;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * The request to show the setup wizard on the next runtime start is honoured exactly once.
+ * A request that stuck would open the wizard on every later profile switch.
+ */
+class ApplicationRuntimeLauncherSetupWizardTest {
+
+ @Test
+ void aRequestIsHonouredOnce() {
+ assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "nothing was requested");
+
+ ApplicationRuntimeLauncher.requestSetupWizard();
+
+ assertTrue(ApplicationRuntimeLauncher.consumeSetupWizardRequest());
+ assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "the request must not stick");
+ }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'`
+Expected: Kompilierfehler, `cannot find symbol ... consumeSetupWizardRequest`.
+
+- [ ] **Step 3: Den Wunsch in `ApplicationRuntimeLauncher` anlegen**
+
+Nach dem Feld `private static Kst4ContestApplication currentRuntime;` einfügen:
+
+```java
+ /**
+ * Whether the next runtime start shows the setup wizard although the profile is set up.
+ * Set by the menu entry and cleared by the start that honours it.
+ */
+ private static final java.util.concurrent.atomic.AtomicBoolean SETUP_WIZARD_REQUESTED =
+ new java.util.concurrent.atomic.AtomicBoolean(false);
+```
+
+Vor `public static boolean switchProfile(` einfügen:
+
+```java
+ /** Asks the next runtime start to show the setup wizard. */
+ static void requestSetupWizard() {
+ SETUP_WIZARD_REQUESTED.set(true);
+ }
+
+ /**
+ * Tells a starting runtime whether the wizard was asked for, and forgets the request.
+ *
+ * @return true exactly once per request
+ */
+ static boolean consumeSetupWizardRequest() {
+ return SETUP_WIZARD_REQUESTED.getAndSet(false);
+ }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'`
+Expected: 1 Test, 0 Fehler.
+
+- [ ] **Step 5: Den Assistenten in `startRuntime` aufrufen**
+
+In `Kst4ContestApplication.java` die Importe ergänzen:
+
+```java
+import kst4contest.view.compose.wizard.SetupWizardLauncher;
+import kst4contest.view.compose.wizard.SetupWizardOutcome;
+```
+
+In `startRuntime` den Anfang ersetzen. Alt:
+
+```java
+ if (!resolveOperatorProfileIfRequired()) {
+ return;
+ }
+
+ ApplicationRuntimeLauncher.setCurrent(this);
+```
+
+Neu:
+
+```java
+ if (!resolveOperatorProfileIfRequired()) {
+ return;
+ }
+
+ /*
+ * The setup wizard, before anything of this profile's runtime exists. It writes
+ * preferences.xml and the ChatController built below reads it like any stored
+ * setting, so there is no running session to bring up to date and no reload.
+ * Blocks until the wizard is closed; see SetupWizardWindow for why that is safe on
+ * either thread this method is called from.
+ */
+ SetupWizardOutcome setupWizardOutcome = SetupWizardLauncher.runIfNeeded(
+ ActiveOperatorProfile.get().getPreferencesRelativeFileName(),
+ ApplicationRuntimeLauncher.consumeSetupWizardRequest());
+
+ ApplicationRuntimeLauncher.setCurrent(this);
+```
+
+Am Ende von `startRuntime`, unmittelbar vor dem Kommentar `Replaces Application.stop()` und dem `Runtime.getRuntime().addShutdownHook(`, einfügen:
+
+```java
+ /*
+ * "Save and connect" in the setup wizard. Here and not earlier: connecting needs the
+ * runtime this method has just finished building. The same path as File -> Connect,
+ * so a refused or failed connection is reported the way it is there.
+ */
+ if (setupWizardOutcome == SetupWizardOutcome.SAVED_AND_CONNECT) {
+ uiDispatcher.runOnUi(this::menuActionConnect);
+ }
+
+```
+
+Die Spec nennt hier `connectFromSettings`. `menuActionConnect` ruft dasselbe `chatcontroller.execute()` und zeigt einen Fehlschlag selbst an; `connectFromSettings` gibt nur einen Text zurück, den das Einstellungsfenster anzeigt, und das ist zu diesem Zeitpunkt nicht der Aufrufer.
+
+- [ ] **Step 6: Bauen und die berührten Tests laufen lassen**
+
+Run: `./gradlew :app-desktop:compileJava :app-desktop:test --tests 'kst4contest.view.*'`
+Expected: BUILD SUCCESSFUL; in `app-desktop/build/test-results/test/` kein `The running runtime is torn down first and the wizard shown afterwards, not the
+ * other way round: a runtime shutting down flushes its pending layout write, and that
+ * must not land on the file the wizard has just written.
+ *
+ * @return true if the new runtime was built
+ */
+ public static boolean rerunSetupWizard() {
+ OperatorProfileSelection active = ActiveOperatorProfile.get();
+
+ if (active == null) {
+ return false;
+ }
+
+ requestSetupWizard();
+ return switchProfile(active.getProfile());
+ }
+```
+
+und die Importe ergänzen, soweit sie fehlen:
+
+```java
+import kst4contest.controller.ActiveOperatorProfile;
+import kst4contest.model.OperatorProfileSelection;
+```
+
+- [ ] **Step 6: Menüaktion in `Kst4ContestApplication`**
+
+Nach der Methode `menuActionToggleSettingsWindow()` einfügen:
+
+```java
+ /**
+ * Options -> setup assistant. Rebuilds the runtime of the active profile with the wizard
+ * in front of it, which costs the running session; hence the question, and hence the
+ * settings edits are settled first, as before a profile switch.
+ */
+ void menuActionOpenSetupWizard() {
+ SettingsWindow.settleThen(() -> {
+ boolean confirmed = ComposeAlert.confirm(
+ kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardTitle(),
+ kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardQuestion(),
+ kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardBody(),
+ kst4contest.view.i18n.CurrentStrings.get().getDialogStartSetupWizard(),
+ kst4contest.view.i18n.CurrentStrings.get().getDialogCancel(),
+ chatcontroller.getChatPreferences().isGUI_darkModeActive());
+
+ if (confirmed) {
+ ApplicationRuntimeLauncher.rerunSetupWizard();
+ }
+ });
+ }
+```
+
+- [ ] **Step 7: Run tests to verify they pass**
+
+Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.MainMenuModelTest' --tests 'kst4contest.view.compose.MainMenuRowScreenTest' --tests 'kst4contest.view.i18n.*'`
+Expected: alle grün.
+
+- [ ] **Step 8: Von Hand prüfen**
+
+1. `./gradlew :app-desktop:run`, mit dem eigenen Profil verbinden.
+2. Im Einstellungsfenster einen Wert ändern, **nicht** übernehmen. „Options → Setup assistant..." wählen.
+3. Erwartet: zuerst die Frage des Einstellungsfensters nach den offenen Änderungen; „Zurück" bricht alles ab, die Sitzung steht noch.
+4. Erneut wählen, Änderungen verwerfen. Erwartet: die Rückfrage „Sitzung beenden …". „Abbrechen" lässt die Sitzung stehen.
+5. Erneut, „Assistent starten". Erwartet: alle Fenster schließen, der Assistent erscheint, die Einstiegsseite bietet für Anmeldung und Station je „neu" und „unverändert".
+6. Beides „unverändert", bis zur Zusammenfassung, „Speichern". Erwartet: das Programm startet neu; Rufzeichen, Locator, Bänder, Fensteranordnung und alle Reiter wie vorher.
+7. `~/.praktiKST/preferences.xml` vor Schritt 5 kopieren und nach Schritt 6 vergleichen (`diff`). Erwartet: kein Unterschied in fachlichen Werten.
+
+Schritt 7 prüft die Annahme der Spec, dass die Laufzeit beim Abbau nicht über die Datei des Assistenten schreibt. Zeigt der Vergleich einen Verlust, das melden und nicht weitermachen.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuBar.kt app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuModel.kt app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuModelTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuRowScreenTest.kt
+git commit -m "Reach the setup wizard from the Options menu"
+```
+
+---
+
+### Task 8: Dokumentation und Abschluss
+
+**Files:**
+- Modify: `docs/PROJECT_CONTEXT.md` (Abschnitt „Important Decisions and Workarounds", ein Punkt am Ende der Liste)
+- Modify: `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` (neuer Abschnitt vor „Station Settings")
+- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` (Schlüssel `profiles.createdWithoutCredentials`)
+- Delete: `docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md`
+
+**Interfaces:**
+- Consumes: das fertige Verhalten aus Task 1 bis 7.
+- Produces: nichts, worauf Code aufbaut.
+
+- [ ] **Step 1: Der Hinweis beim Anlegen eines Profils**
+
+Der Text schickt den Nutzer heute in den Reiter „Station". Nach dem Wechsel erscheint jetzt der Assistent.
+
+In `strings_de.properties` die Zeile `profiles.createdWithoutCredentials=…` ersetzen durch:
+
+```properties
+profiles.createdWithoutCredentials=Das Profil „{0}" wurde ohne Rufzeichen und Passwort angelegt. Nach dem Wechsel zu diesem Profil fragt der Einrichtungsassistent beides ab.
+```
+
+In `strings_en.properties` die Zeile mit demselben Schlüssel ersetzen durch:
+
+```properties
+profiles.createdWithoutCredentials=The profile "{0}" was created without callsign and password. After switching to it, the setup assistant asks for both.
+```
+
+Run: `grep -rn 'profilesCreatedWithoutCredentials\|createdWithoutCredentials' app-desktop/src/test`
+Jeden Test, der den alten Wortlaut festhält, auf den neuen ändern.
+
+- [ ] **Step 2: `docs/PROJECT_CONTEXT.md`**
+
+Am Ende der Liste unter „Important Decisions and Workarounds" anfügen:
+
+```markdown
+- **The setup wizard writes `preferences.xml` and does not touch a running session.** It runs
+ in `startRuntime` after the profile is resolved and before the `ChatController` exists, on
+ a `ChatPreferences` of its own, so what it stores is read like any stored setting. That is
+ why it needs neither `SettingsDraft` nor the tab states: there is no session to bring up to
+ date. From the menu the runtime is torn down first and the same profile restarted
+ (`ApplicationRuntimeLauncher.rerunSetupWizard`), which costs the session and asks first. A
+ profile counts as unconfigured when its callsign is empty or it still carries the bundled
+ template's credentials (`LoginConfiguration`); there is no flag for it in the file. Stage 1
+ asks for name, login, locator, bands and chat category; the reasons and the later stages
+ are in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`.
+```
+
+- [ ] **Step 3: Handbuch, deutsch**
+
+In `github_docs/de-Konfiguration.md` den ersten Absatz nach der Sprachzeile ersetzen. Alt:
+
+```markdown
+Nach dem ersten Start öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten).
+```
+
+Neu:
+
+```markdown
+Beim ersten Start fragt der **Einrichtungsassistent** das Nötigste ab (siehe unten). Danach öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten).
+```
+
+Unmittelbar vor `## Station Settings (Stationseinstellungen)` einfügen:
+
+```markdown
+## Einrichtungsassistent (ab v1.51)
+
+Solange ein Profil kein eigenes Rufzeichen hat, startet es mit dem Einrichtungsassistenten. Das gilt für die erste Installation und für jedes neu angelegte oder duplizierte Operator-Profil.
+
+Der Assistent fragt:
+
+1. **Persönliches** – Sprache und Anzeigename im Chat.
+2. **Anmeldung** – Rufzeichen und Passwort des ON4KST-Kontos.
+3. **Standort und Bänder** – Locator, aktive Bänder und Chatkategorie. Die Kategorie wird aus den Bändern vorgeschlagen und lässt sich ändern. Ein zweiter Chat ist freiwillig.
+4. **Zusammenfassung** – erst **Speichern** schreibt die Einstellungen. **Speichern und verbinden** meldet danach gleich am Chat an.
+
+Hat das Profil schon eine Station (etwa nach dem Duplizieren), fragt die erste Seite, ob sie **unverändert** bleiben oder **neu eingerichtet** werden soll. So braucht ein weiterer Operator an derselben Station nur Namen und Anmeldung einzutragen.
+
+**Später** schließt den Assistenten, ohne etwas zu schreiben. Er erscheint beim nächsten Start des Profils wieder, solange das Rufzeichen fehlt.
+
+Über **Options → Einrichtungsassistent...** lässt er sich jederzeit erneut aufrufen. Dabei wird die laufende Sitzung nach einer Rückfrage beendet und das Profil neu gestartet. Für einzelne Änderungen im Betrieb ist das Einstellungsfenster gedacht.
+
+Logprogramm, Rotor, AirScout und DX-Cluster-Server fragt der Assistent noch nicht ab; sie behalten ihre Werte und werden wie bisher im Einstellungsfenster eingestellt.
+
+---
+
+```
+
+Die Versionsangabe „ab v1.51" gegen `gradle.properties` prüfen und auf die Version setzen, in der die Änderung erscheint. Kein Versionssprung in `gradle.properties` selbst.
+
+- [ ] **Step 4: Handbuch, englisch**
+
+In `github_docs/en-Configuration.md` den ersten Absatz ersetzen. Alt:
+
+```markdown
+After the first start, the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off).
+```
+
+Neu:
+
+```markdown
+On the first start, the **setup assistant** asks for the essentials (see below). After that the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off).
+```
+
+Unmittelbar vor `## Station Settings` einfügen:
+
+```markdown
+## Setup Assistant (since v1.51)
+
+As long as a profile has no callsign of its own, it starts with the setup assistant. This applies to the first installation and to every newly created or duplicated operator profile.
+
+The assistant asks for:
+
+1. **Personal** – language and the name shown in the chat.
+2. **Login** – callsign and password of the ON4KST account.
+3. **Location and bands** – locator, active bands and chat category. The category is suggested from the bands and can be changed. A second chat is optional.
+4. **Summary** – nothing is written until you click **Save**. **Save and connect** logs into the chat right afterwards.
+
+If the profile already has a station (after duplicating one, for example), the first page asks whether to leave it **unchanged** or to **set it up anew**. A further operator at the same station then only enters a name and a login.
+
+**Later** closes the assistant without writing anything. It appears again on the next start of the profile as long as the callsign is missing.
+
+**Options → Setup assistant...** opens it again at any time. This ends the running session after a confirmation and restarts the profile. Use the settings window for single changes during operation.
+
+The assistant does not ask about log program, rotator, AirScout and DX cluster server yet; they keep their values and are configured in the settings window as before.
+
+---
+
+```
+
+- [ ] **Step 5: Der ganze Bau**
+
+Run: `./gradlew clean build`
+Expected: BUILD SUCCESSFUL.
+
+Danach, weil der Rückgabewert allein nichts beweist:
+
+```bash
+grep -l '